updated documentation

This commit is contained in:
David Turner 2000-07-26 19:07:15 +00:00
parent 5fe4c00ed2
commit b190572be5
4 changed files with 2290 additions and 17 deletions

352
docs/freetype2.html Normal file
View File

@ -0,0 +1,352 @@
<html>
<head>
<title>FreeType 2 Introduction</title>
<basefont face="Georgia, Arial, Helvetica, Geneva">
<style content="text/css">
P { text-align=justify }
H1 { text-align=center }
H2 { text-align=center }
LI { text-align=justify }
</style>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<font size=1>http://www.freetype.org</font><p>
<center>
<a href="freetype.html">
<img src="image/freetype.jpg" width=550 height=105 alt="The FreeType Project" border=0></a>
<h1>An Introduction to FreeType 2</h1>
</center>
<center><table width=750 cellspacing=10 cellpadding=30><tr><td>
<hr><p>
DOCUMENT INDEX:<br>
<ul>
<li><a href="#what">What is FreeType 2 ?</a>
<li><a href="#features">Features</a>
<li><a href="#requirements">Requirements</a>
<li><a href="#patents">Patents issues</a>
</ul><p>
<hr><p>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="what">What is FreeType 2 ?</h2>
</td></tr><tr><td>
<p>The FreeType project is a team of volunteers who develop free, portable
and high-quality software solutions for digital typography. We specifically
target embedded systems and focus on bringing small, efficient and
ubiquitous products.</p>
<p>the FreeType 2 library is our new software font engine. It has been
designed to provide the following important features:</p>
<ul>
<li><p>
<b>A universal and simple API to manage font files:</b><br>
<ul>
<p>The FreeType 2 API is simple and easy to use. It supports both
bitmapped and scalable fonts and is well-suited to manage font
files of all formats. Unlike other font libraries, FreeType 2
returns and manages outline font data (images & metrics).</p>
</ul>
</p></li>
<li><p>
<b>Support for several font formats through loadable modules:</b><br>
<ul>
<p>FreeType 2 uses <em>"font drivers"</em>. Each driver is a loadable
module used to support one specific font format. Each driver can also
provide specific extensions used to access format-specific features of
the font.</p>
</ul>
</p></li>
<li><p>
<b>High-quality anti-aliasing:</b><br>
<ul>
<p>FreeType 2 produces etremely smooth outlines at small sizes, with its new
anti-aliasing renderer, which produces bitmaps with 256-levels of gray.
It uses a new algorithm that has been specifically designed to render
small complex shapes (like glyphs) at high speed. Indeed, it's even
faster than the monochrome renderer for small character sizes (under
20 pixels) !!
</p>
</ul>
<li><b>High portability & performance:</b><br>
<ul>
<p>The FreeType 2 source code is written in ANSI C and runs on any
platform with a compliant compiler. Client applications can
provide their own memory manager or input stream to the library
(which means that font files can come from any place: disk,
memory, compressed file, network, etc..).
</p>
</ul>
</ul>
<p>Note that <em>the beta of FreeType 2 is available <b>now</b></em>. For more
info, check our <a href="download.html">Download page</a> or see the source
and its diffs through our <a href="cgi-bin/cvsweb.cgi">CVS Web interface</a>.
</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="features">Features</h2>
</td></tr><tr><td>
<h3>Supported font formats</h3>
<p>FreeType 2 readily supports the following font formats:</p>
<ul>
<li>TrueType files (.ttf) and collections (.ttc)</li>
<li>Type 1 font files both in ASCII (.pfa) or binary (.pfb) format</li>
<li>Type 1 Multiple Master fonts. The FreeType 2 API also provides
routines to manage design instances easily</li>
<li>Type 1 CID-keyed fonts</li>
<li>OpenType/CFF (.otf) fonts</li>
<li>CFF/Type 2 fonts</li>
<li>Adobe CEF fonts (.cef), used to embed fonts in SVG documents
with the Adobe SVG viewer plugin.</li>
<li>Windows FNT/FON bitmap fonts</li>
</ul>
<p>Note that Apple's TrueType GX fonts are supported as normal TTFs,
(the advanced tables are ignored).</p>
<p>Besides, it's possible to add support for new font formats by providing
a specific <em>font driver</em> module. Modules can be added either at
build time (when recompiling the library), or at <em>run-time</em>;
this allows, for example, applications to register their own
font driver to support program-specific formats.</p>
<h3>Patent-free automatic hinter</h3>
<p>TrueType fonts are normally renderered (hinted) with the help of a
specific bytecode where the behaviour of a few opcodes is patented by
Apple. We're currently in contact with Apple to discuss the importance
of such patents and their use in open source projects like FreeType.
</p>
<p>In the meantime, we have developped our own alternative technology that
is capable of automatically hinting scalable glyph images. It is
now part of the FreeType 2 source tree as the "autohint" module,
and is used to hint glyphs when the bytecode interpreter is disabled
(through a configuration macro when building the engine). Note that
the auto-hinter is also used to handle glyphs in other formats like
CFF and Type 1.</p>
<p>The auto-hinter provides pretty good results (in some cases, it even
significantly improves the output of poorly hinted fonts) but we'll
continue to improve it with each new release of FreeType to achieve
the highest possible quality.</p>
<h3>Modular design:</h3>
<p>The design of FreeType 2 is extremely modular as most features are
supported through optional modules. This means it's easily possible to
only compile the features you need. As each module is between
10 and 20 Kb in size, it's possible to build a bare-bones
font engine that supports anti-aliasing in about 30 Kb !!</p>
<p>Configuration is performed by modifications of only two header
files (one to select global features, another one to select modules)
and don't need tweaking of source code. Note that it is however
possible to provide your own implementation of certain components.</p>
<p>For example, when building on Unix, the engine will automatically
use memory-mapped files when available on the target platform,
thus significantly increasing font file i/o.</p>
<p>Due to its very flexible design, it is possible to add, remove and
upgrade modules at run-time.</p>
<h3>Advanced glyph management</h3>
<p>The API comes with a standard extension used to extract individual
glyph images from font files. These images can be bitmaps, scalable
bezier outlines or even anything else. (e.g. bi-color or metafont
glyphs, as long as they're supported by a module).</p>
<p>Each scalable glyph image can be transformed, measured and
rendered into a monochrome or anti-aliased bitmaps easily
through a uniform interface.
This allows client applications to easily cache glyphs or
perform text rendering effects with minimal difficulty
(look at the FreeType 2 Tutorial to see how to render
rotated text with very few lines of code).
</p>
<h3>Advanced font access</h3>
<p>The FreeType 2 API is useful to retrieve advanced information from
various fonts:</p>
<ul>
<li>vertical metrics are available whenever found in the font file</li>
<li>kerning distances are available when found in the font file. It
is also possible to "attach" a given additional file to a given
font face. This is useful to load kerning distances from an
.afm file into a Type 1 face for example.</li>
<li>provides ASCII glyph names whenever available in the font
(TrueType, OpenType, Type1, etc..)</li>
<li>provides access to important tables for SFNT-based font formats
(i.e. TrueType, OpenType, CEF, etc..), like the name table,
font header, maximum profile, etc...</li>
<li>automatic synthesis of Unicode-based character maps for
those fonts or formats that do not provide one. This is
extremely useful with Type 1 fonts which are normally
limited to a stupid 256-characters encoding.</li>
</ul>
<h3>Simple & clean API</h3>
<p>The FreeType 2 high-level API is simple and straightforward, as it
has been specifically designed to make the most commmon font operations
easy</p>
<p>As a comparison, the number of function calls needed to perform a
the tasks of font face creation/opening and glyph loading/rendering
has been reduced by a factor of 4 !!</p>
<p>The API is also independent of any font-format specific issue, though
it provides standard extensions to access format-specific tables and
information. More extensions can also be easily added through new
modules</p>
<h3>Robust & Portable code</h3>
<p>Because it is written in industry-standard ANSI C, FreeType 2 compiles
on all platforms with a compliant compiler. Because the default build
only relies on the C library, it is free of any system-specific
dependencies, even if it is possible to "enhance" certain components
by providing a specific implementation.</p>
<p>The code doesn't use global or static variables. Client applications
can provide their own memory manager. Font files can be read from
a disk file, memory, or through a client-provided input stream. This
allows to support compressed font files, remote fonts, fonts embedded
in other streams (e.g. Type42 fonts), etc..</p>
<p>An advanced i/o sub-system is used to optimise file access, as well
as reduce memory usage of the library when the file is memory-based
( ROM, RAM, memory-mapped ).</p>
<h3>Open Source & Vendor Independence</h3>
<p>Finally, FreeType 2 is released under its own BSD-like open source
license, one of the less restricting licenses available, and this
means that:</p>
<ul>
<li><p>
It can be included in all kinds of products, be they proprietary
or not.
</p></li>
<li><p>
As any module can be added or replaced anytime, any third party
vendor has the ability to provide its own set of modules (under
its own license) in order to support proprietary font formats or
more advanced features (e.g. a new auto-hinter, or a new
anti-aliasing renderer for LCDs or TV screens).
</p></li>
</ul>
<p>One could even imagine an application using the FreeType 2 API with
a "wrapper" module used to access system-specific fonts (like through
the Windows GDI). This would mean native font support with more portable
application code (as simply changing the wrapper module would be required
to port the application to another system).</p>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="requirements">Requirements</h2>
</td></tr><tr><td>
<p>FreeType 2 is written in ANSI&nbsp;C and should compile with no problems
on a great variety of platforms. We have taken care of removing all
compilation warnings from major compliant compilers. Detailed compilation
instructions are provided in the software archive.</p>
<p>This version of the library has been succesfully compiled and run
under the following systems: Dos, OS/2, Windows, Macintosh, Unix
(including the 64-bits DEC Unix, a.k.a. "True64"). You should not
encounter major problems compiling it on any other kind of platform.
In all cases, contact us if you do.</p>
<p>Note that a small set of demonstration programs is also separately
available. They include a tiny graphics sub-system that is used to
display and show-off the library's capabilities on the following
platforms: X11, MacOS, OS/2 & Windows.</p>
<p>Please visit our <a href="http://www.freetype.org/download.html">
Download section</a> to access the software archives.</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="patents">Patents issues</h2>
</td></tr><tr><td>
<p>The FreeType 2 source code includes a TrueType bytecode interpreter that
is covered by the Apple patents. However, this piece of code is never
compiled by default in this release (unlike in previous betas) making
a default build of the library <em>entirely patent-free !!</em></p>
<p>Note that in order to compile the interpreter, one needs to define
the configuration macro <tt><b>TT_CONFIG_OPTION_BYTECODE_INTERPRETER</b></tt> configuration
macro in the file "<tt>ftoption.h</tt>". More details are available in
the software archive. Note that the use of the interpreter is normally
protected by US, UK and French patents. In the event you'd absolutely
need it, you may have to <a href="mailto:patents@apple.org">contact
Apple legal department</a> for licensing conditions, depending on your
location and the places you distribute/sell your products.</p>
<p>Please do not ask us any detailed information regarding licensing, as
we're still discussing with Apple this issue, we're unable to inform
the public of what's currently going on..</p>
</td></tr></table>
<hr>
<p>
<a href="index.html">Back to FreeType homepage</a><p>
</td></tr></table>
</body>
</html>

502
docs/ft2faq.html Normal file
View File

@ -0,0 +1,502 @@
<html>
<head>
<title>FreeType 2 FAQ</title>
<basefont face="Georgia, Arial, Helvetica, Geneva">
<style content="text/css">
P { text-align=justify }
H1 { text-align=center }
H2 { text-align=center }
LI { text-align=justify }
</style>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<font size=1>http://www.freetype.org</font><p>
<center>
<a href="freetype.html">
<img src="image/freetype.jpg" width=550 height=105 alt="The FreeType Project" border=0></a>
<h1>The FreeType 2 FAQ</h1>
</center>
<center><table width=750 cellspacing=10 cellpadding=30><tr><td>
<hr><p>
DOCUMENT INDEX:<br>
<ul>
<li><p><a href="#general">General</a>
<ul>
<li><a href="#general-dead">I thought the FreeType project was dead. It this true?</a></li>
<li><a href="#general-long">Why did it take so long to release FreeType 2?</a></li>
<li><a href="#general-unix">Is FreeType 2 a Unix-only project?</a></li>
<li><a href="#general-x11">When will X11 support anti-aliased glyphs?</a></li>
<li><a href="#general-ft1">Is FreeType 2 backwards compatible with 1.x?</a></li>
<li><a href="#general-edit">Can I use FreeType 2 to edit fonts or create new ones?</a></li>
</ul></p>
</li>
<li><p><a href="#builds">Compilation & Configuration</a>
<ul>
<li><a href="#builds-compile">How do I compile the FreeType 2 library?</a></li>
<li><a href="#builds-config">How do I configure my library build?</a></li>
<li><a href="#builds-modules">How do I select the modules I need?</a></li>
<li><a href="#builds-flat">How do I compile all FreeType 2 files in a single directory?</a></li>
</ul>
</p></li>
<li><p><a href="#library">Using the FreeType 2 library</a></p></li>
<li><p><a href="#autohint">The FreeType 2 Autohinter</a>
<ul>
<li><a href="#autohint-license">Under which license is the auto-hinter released ?</a></li>
<li><a href="#autohint-work">How does auto-hinting work in FreeType 2 ?</a></li>
<li><a href="#autohint-cjk">Why doesn't the auto-hinter work well with CJK fonts ?</a></li>
</ul>
</p></li>
<li><p><a href="#other">Other questions</a>
<ul>
<li><a href="#other-antialias">What is the anti-aliasing algorithm used in the FreeType 2 renderer?</a></li>
<li><a href="#other-opentype">When will FreeType 2 support OpenType ?</a></li>
</ul></p>
</li>
</ul><p>
<hr><p>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="general">General questions & answers</h2>
</td></tr><tr><td>
<a name="general-dead">
<h3>I.1. I though the FreeType project was dead. Is this true?</h3>
<ul>
<p>Well, not exactly :-) It's true that the TrueType patents issues
have been less than a graceful event to handle but it didn't not
really killed the project per se, as Apple hasn't made an official
statement yet regarding the use of the patented "technology" in
open source projects (or other products).</p>
<p>We have thus continued updating FreeType 1.x, and started developping
FreeType 2 with the idea of providing this time a completely patent
free font engine. However, we largely preferred not to broadly
communicate about it until we've got a satisfying implementation
to show.</p>
</ul>
<a name="general-long">
<h3>I.2. Why did it take so long to release FreeType 2?</h3>
<ul>
<p>Several factors come to mind. The first one is that FreeType 2 is
a much more complex and dense project that was mostly developed
on non-working hours. And surely some important changes in the
life (like marriage, new jobs and kids) of some the FreeType
developers cannot be ignored :-)</p>
<p>A second one is that a first version of the library was designed
one year ago (and already worked with a multitude of font drivers),
though with a design that was judged by its authors as well as
beta testers as not enough flexible or consistent. In short, it worked
well but we were not exactly proud of it (call us perfectionists).
It has then be significantly reworked to become what we're now
distributing as FreeType 2</p>
<p>Finally, it would have been hard to distribute such a library without
an alternative technology to replace the patented bytecode interpreter.
This involved significant research work that could only be performed
correctly full-time, and we had to found a company to fund such a
development and still make it available under a BSD-like license.
Huge thanks to <a href="http://www.catharon.com">Catharon Productions, Inc.</a>
for their commitment to this project.</p>
<p>And of course, we added support for more font files, and we'll
continue to as long as the specs are available and that we find an
interest in it. For example, FreeType 2 is to date the only
software library available on the market that supports the new
Adobe "CEF" font format.</p>
</ul>
<a name="general-unix">
<h3>I.3. Is FreeType 2 a Unix-only project?</h3>
<ul>
<p>Absolutely not, even though many people still seem to think so :-)
FreeType 2, just like version 1.x, can be compiled on any platform with
an ANSI compiler. Some beta versions of the library are even heavily
used in brand new OSes (see the <a href="http://www.atheos.cx">AtheOS
</a> screenshots for examples).</p>
<p>The library is itself mainly developped on several platforms
(Windows & Linux, though a great deal has also been achieved on OS/2)
and the code is highly generic and modular to adapt even the most
strict environments like low-memory embedded systems.</p>
</ul>
<a name="general-x11">
<h3>I.4. When will X11/XFree support anti-aliased text?</h3>
<ul>
<p>This question isn't exactly related to FreeType as we have no direct
connection to the XFree people, but we've been asked so frequently
about it that it deserves a prominent place in this FAQ :-)</p>
<p>FreeType has been capable of anti-aliasing since version 1.0. The
reason why XFree doesn't support it is directly related to the
limitations of the design and specification of X11. More specifically:</p>
<ul>
<li><p>
X11 assumes that all glyph images are monochrome bitmaps,
hence the X font library and server are unable to send anything
else to the X server.
</p></li>
<li><p>
Even if the X font library/server was able to generate anti-aliased
bitmaps (and this has been already done through extensions), the X
rendering model doesn't allow translucent composition of "gray" pixmaps
onto an arbitrary drawable.
</p></li>
</ul>
<p>As both the font and rendering models of X11 are limited, it's basically
impossible to draw anti-aliased glyphs without performing <em>huge</em>
hacks within the server.</p>
<p>Note that Keith Packard, from XFree fame, has recently started working
on a new rendering model for X11 in order to support new features
(mainly transparency and anti-aliased fonts). This will be provided
through protocol extensions. The question of knowing wether legacy X
applications will be able to display anti-aliased text is still very
uncertain.
</p>
</ul>
<a name="general-ft1">
<h3>I.5. Is FreeType 2 backwards compatible with FreeType 1.x?</h3>
<ul>
<p>Not directly, though we had the project to provide an optional binary
compatibility layer on top of it in order to easily re-link applications
with the new version. However, this idea has been dropped as it is
possible to install and use the two versions independtly on any
system (read: no namespace conflicts).</p>
<p>The FreeType 2 API is a lot simpler than the one in 1.x while being
much more powerful. We thus encourage you to adapt your source code
to it as this should not involve much work.</p>
</ul>
<a name="general-edit">
<h3>I.6. Can I use FreeType 2 to edit fonts or create new ones?</h3>
<ul>
<p>The answer is a definitive NO, because the library was specifically
designed to <em>read</em> font files with small code size and very
low memory usage.</p>
<p>We thus do not plan to support editing or creation in the font
engine in any way, as this would imply a complete rewrite. This
doesn't mean that we won't introduce a font editing/creation library
in the future, as this really depends on how many people are asking
for it (or how much they would be willing to pay for it), as well as
the time of the FreeType developers.</p>
<p>Do not expect anything in this direction until we officially announce
something though. There are other axis of development for this project
(like text-layout capabilities, glyph caching, etc..) that may be more
important to us at the moment..</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="builds">Compilation & Configuration</h2>
</td></tr><tr><td>
<a name="builds-compile">
<h3>II.1. How do I compile the FreeType 2 library?</h3>
<ul>
<p>The library can be compiled in various ways, and a detailed documentation
is available in the file "<tt>freetype2/docs/BUILD</tt>". However, we'll
summarize the process to a few cases:</p>
<h3>a. by using the command-line 2 build system</h3>
<p>The engine comes with a sophisticated build system that is used
to configure and compile a build of the library. You'll need
<em>GNU Make</em> installed on your platform (NOTE: It will <b>not</b>
work with other Make tools).</p>
<p>Basically, you'll need to invoke <tt>make</tt> a first time in the
top-level FreeType 2 directory in order to setup the build. This will
detect your current platform and choose a configuration sub-makefile to
drive the build. A specific compiler can be selected on some platforms
by providing an additional target. For example, on Win32:</p>
<ul>
<li><b><tt>make visualc</tt></b> will select the Visual C++ compiler</li>
<li><b><tt>make lcc</tt></b> will select the Win32-lcc compiler</li>
</ul>
<p>Note that on Unix, the first time make is called, a configure script
located in "<tt>freetype2/builds/unix</tt>" will be run in order to
automatically detect the platform & compiler.</p>
<p>A summary will be displayed showing the detected platform and compiler
selected. You'll then be able to start the build by invoking <tt>make</tt>
a second time. In case of problem, consult the <tt>BUILD</tt> document.</p>
<h3>b. by direct compilation</h3>
<p>You can also directly compile the library from the command line by
using these simple rules:</p>
<ul>
<li><p>
You should place the directories "<tt>freetype2/include</tt>" and
"<tt>freetype2/src</tt>" in your include path in order to compile
any component of the library. You can also add the system-specific
build directory (i.e. "<tt>builds/<em>system</em>/</tt>") in the
case where an alternate implementation of some of the components
is available there (e.g. the memory-mapped i/o implementation
on some Unix systems).
</p></li>
<li><p>
The components of the library are located in sub-directories of
"<tt>src</tt>", for example: "<tt>src/base</tt>",
"<tt>src/truetype</tt>", etc..
</p></li>
<li><p>
Each component is normally compiled through a single C file that
"wraps" other sources in the component's directory. For example,
your should compile the TrueType font driver by compiling the
file "<tt>src/truetype/truetype.c</tt>". The list of C files to
compile for a feature-complete build of the library is given in
the <tt>BUILD</tt> document.
</p></li>
</ul>
<h3>c. in a graphical IDE</h3>
<ul>
<p>Well, the process is vastly similar to the one described in b.,
except that you need to set the include paths, source code paths,
etc.. in dialog boxes before running the compilation.
</p>
</ul>
</ul>
<a name="builds-config">
<h3>II.2. How do I configure my build of the library?</h3>
<ul>
<p>Each build of the library is configured through two header files
located in "<tt>include/freetype/config</tt>":</p>
<ul>
<li><p><b><tt>ftoption.h</tt></b><br>
This file contains various configuration macros whose definition
can be toggled on a per-build basis. Each macro is heavily
commented in this file's comment, and we invite you to refer
to it directly.</p></li>
<li><p><b><tt>ftmodule.h</tt></b><br>
This file contains the list of all the modules that are initially
registered (added) when the function <b><tt>FT_Init_FreeType</tt></b>
is called. See the next answer to know how to change it and
why it may be important.</p></li>
</ul>
<p>Alternatively, some specific implementations of some FT2 components
can be provided in a "<tt>builds/<em>system</em>/</tt>" directory
(e.g. the Unix-specific <tt>ftsystem.c</tt> that uses memory-mapped
file for i/o).</p>
</ul>
<a name="builds-modules">
<h3>II.3. How do I select the modules I need in my build?</h3>
<ul>
<p>The function <tt><b>FT_Init_FreeType</b></tt> creates a new instance
of the FT2 library and registers a set of "default" modules before
returning to the calling application. Its default implementation
is in the file "<tt>src/base/ftinit.c</tt>".</p>
<p>The list of default modules used by <tt>ftinit.c</tt> is located in
the configuration file "<tt>include/freetype/config/ftmodule.h</tt>".
It is normally automatically generated by the build system by
invoking the "<tt><b>make modules</b></tt>" command in the top
level FT2 directory (note: only works with GNU Make, you can
edit the file by hand otherwise). It does so by parsing all
sub-directories of "<tt>src</tt>" that contain a file named
<tt>module.mk</tt>.</p>
<p>Note that a specific port or project is free to provide its own
implementation of <tt>ftinit.c</tt> in order to ensure a different
initialisation sequence. For example, one could do something like:</p>
<ul>
<li><p>compile each module as a shared library (DLL or .so) with
a common "entry point" to retrieve a pointer to its
module class (there is already some code that allows this
when compiling each module).</p></li>
<li><p>place these modules in a directory like
"<tt>/usr/lib/freetype2/modules/</tt>"</p></li>
<li><p>provide an implementation of <tt>ftinit.c</tt> that would
scan the directory for valid modules.</p></li>
</ul>
<p>This example only emphasize the flexibility that is left to
developers when building the library.</p>
</ul>
<a name="builds-flat">
<h3>II.4. How do I compile all FreeType 2 files in a single directory?</h3>
<ul>
<p>Some projects may need, for the sake of simplicity or ease of
building, to compile the FT2 library with all source files
copied to a single directory. This is possible.</p>
<p>To do so, you'll need to copy all source files located under
"<tt>src</tt>" to your own directory (you must retain the
include files in a distinct hierarchy though), then compile
each of the FreeType 2 component with the macro
<tt><b>FT_FLAT_COMPILE</b></tt>. This will change the way
<tt><b>#include</b></tt> works during the build.</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="library">Using the FreeType 2 library</h2>
</td></tr><tr><td>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="autohint">The FreeType 2 auto-hinter</h2>
</td></tr><tr><td>
<a name="autohint-license">
<h3>IV.1. Under which license is the FreeType 2 auto-hinter released</h3>
<ul>
<p>The auto-hinter was initially designed and implemented under contract
for <a href="http://www.catharon.com">Catharon Productions, Inc</a>
which gladly accepted to released it under an open-source license
compatible with the FreeType one.</p>
<p>This license can be found in "<tt>src/autohint/CatharonLicense.txt</tt>"
and requires that you cite Catharon Productions in your documentation
(just like you do with FreeType) when using the auto-hinting module.</p>
<p>Other than that, you still have the same freedom than with the good old
FreeType license. Enjoy !</p>
</ul>
<a name="autohint-work">
<h3>IV.2. How does the auto-hinter works ?</h3>
<ul>
<p>Well, a complete description would be difficult. Have a look at the
dedicated <a href="autohinting/index.html">auto-hinter pages</a> on the FreeType
site, as they describe most of its details with graphics and explanations.
You could also look at the source code if you want to :-)</p>
<p>To give a few details, the auto-hinter is used to perform grid-fitting
on scalable font formats that use bezier outlines as their primary glyph
image format (this means nearly all scalable font formats today). When
a given font driver doesn't provide its own hinter, the auto-hinter is
used by default. When a format-specific hinter is provided, it is still
possible to use the auto-hinter using the
<tt><b>FT_LOAD_FORCE_AUTOHINT</b></tt> bit flag when calling
<tt>FT_Load_Glyph</tt>.</p>
<p>The auto-hinter currently doesn't use external hints to do its job,
as it automatically computes global metrics (when it "opens" a font
for the first time) and glyph "hints" from their outline. Note that
we plan the ability to specify external hints, given that it is based
on a constraint system. That could be used to support native hints
in Type 1/Type 2 fonts, for example.</p>
</ul>
<a name="autohint-cjk">
<h3>IV.3. Why does the auto-hinter doesn't work correctly with CJK fonts ?</h3>
<ul>
<p>The auto-hinter was first designed to manage and hint latin-based fonts,
as they consist of most of the fonts available today. It doesn't hint
asian fonts, as well as a few other complex scripts, because we didn't
put enough research on the topic yet. Hinting CJK isn't really more
difficult than latin, just different with a set of different constraints
(basically, more distortion of glyphs is acceptable as long as certain
features like triple-stem positions are respected more strictly..).</p>
<p>We thus plan to handle such a case rather rapidly.. Please be patient.</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="other">Other questions</h2>
</td></tr><tr><td>
<a name="other-antialias">
<h3>V.1. What is the anti-aliasing algorithm used by FreeType 2 ?</h3>
<ul>
<p>The algorithm has been specifically designed for FreeType. It is
based on ideas that were originally found in the implementation
of the <a href="http://www.levien.com/libart">libArt</a> graphics
library to compute the <em>exact pixel coverage</em> of a vector
image with absolutely now sub-sampling/filtering.
</p>
<p>However, these two implementations are radically distinct and use
vastly different models. The FreeType 2 renderer is optimized
specifically for rendering small complex shapes, like glyphs, at
very high speed while using very few memory; while libArt shines
at general shape/polygon processing, especially large ones.</p>
<p>The FT2 anti-aliasing renderer is indeed <em>faster</em> than the
monochrome renderer for small character sizes (typically &lt; 20 pixels).
This is explained because the monochrome renderer must perform two
passes on the outline in order to perform drop-out control according
to the TrueType spec (we could drop this requirement later though).</p>
<p>We'll try to document its design in a later document, though this is
not a priority for now.</p>
</ul>
<a name="other-opentype">
<h3>V.2. When will FreeType 2 support OpenType ?</h3>
<ul>
<p>Well, the engine already reads OpenType/CFF files perfectly. What it
doesn't do is handle "OpenType Layout" tables yet.</p>
<p>FreeType 1 comes with a set of extensions that are used to load
and manage OpenType Layout tables. It even has a demonstration program
named "<tt>ftstrtto</tt>" used to demonstrate its capabilities that
runs pretty smooth.</p>
<p>For FreeType 2, we have decided that the layout operations provided
through these tables is better placed in a specific text-layout library,
(many people having asked for such a thing). This new engine would not
depend on FT2 explicitely and will be developed as a separate project.
We plan to announce it in a few weeks with all gory details,
once the definitive 2.0 release of FreeType has been made.</p>
</ul>
</td></tr></table>
<hr>
<p>
<a href="index.html">Back to FreeType homepage</a><p>
</td></tr></table>
</body>
</html>

View File

@ -542,10 +542,11 @@
</font>
<p>The parameter <tt>render_mode</tt> is a set of bit flags used
to specify how to render the glyph image. Set it to 0 to render
a monochrome bitmap, or to <tt>ft_render_mode_antialias</tt> to
generate a high-quality (256 gray levels) anti-aliased bitmap
from the glyph image.</p>
to specify how to render the glyph image. Set it to 0, or the
equivalent <tt>ft_render_mode_normal</tt> to render a high-quality
anti-aliased (256 gray levels) bitmap, as this is the default.
You can alternatively use <tt>ft_render_mode_mono</tt> if you
want to generate a 1-bit monochrome bitmap.</p>
<p>Once you have a bitmapped glyph image, you can access it directly
through <tt><b>glyph->bitmap</b></tt> (a simple bitmap descriptor),
@ -675,10 +676,23 @@
of (0,0) will be used). The vector coordinates are expressed in
1/64th of a pixel (also known as 26.6 fixed floats).</p>
<p><em>NOTA BENE: The transform is applied every glyph that is loaded
through <tt>FT_Load_Glyph</tt>. Note that loading a glyph bitmap
with a non-trivial transform will produce an error..</em></p>
<font color="red">
<p>NOTA BENE: The transform is applied to every glyph that is loaded
through <tt>FT_Load_Glyph</tt> and is <b>completely independent
of any hinting process.</b> This means that you won't get the same
results if you load a glyph at the size of 24 pixels, or a glyph at
the size at 12 pixels scaled by 2 through a transform, because the
hints will have been computed differently (unless, of course you
disabled hints).</em></p></font>
<p>If you ever need to use a non-orthogonal transform with optimal
hints, you first need to decompose your transform into a scaling part
and a rotation/shearing part. Use the scaling part to compute a new
character pixel size, then the other one to call FT_Set_Transform.
This is explained in details in a later section of this tutorial.</p>
<p>Note also that loading a glyph bitmap with a non-identity transform
will produce an error..</p>
<hr>
<h3>
@ -721,7 +735,7 @@
if (error) continue; // ignore errors
// convert to an anti-aliased bitmap
error = FT_Render_Glyph( face->glyph, ft_render_mode_antialias );
error = FT_Render_Glyph( face->glyph, ft_render_mode_normal );
if (error) continue;
// now, draw to our target surface
@ -790,7 +804,7 @@
for ( n = 0; n &lt; num_chars; n++ )
{
// load glyph image into the slot (erase previous one)
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER | FT_LOAD_ANTI_ALIAS );
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
if (error) continue; // ignore errors
// now, draw to our target surface
@ -815,12 +829,15 @@
<li><p>
We do not use <tt>FT_LOAD_DEFAULT</tt> for the loading mode, but
the two bit flags <tt><b>FT_LOAD_RENDER</b></tt> and
<tt><b>FT_LOAD_ANTI_ALIAS</b></tt>. The first flag indicates that
the glyph image must be immediately converted to a bitmap, and
the second that it should be renderer anti-aliased. Of course, this
is also a shortcut that avoids calling <tt>FT_Render_Glyph</tt>
explicitely but is strictly equivalent..
the bit flag <tt><b>FT_LOAD_RENDER</b></tt>. It indicates that
the glyph image must be immediately converted to an anti-aliased
bitmap. This is of course a shortcut that avoids calling
<tt>FT_Render_Glyph</tt> explicitely but is strictly equivalent.</p>
<p>
Note that you can also specify that you want a monochrome bitmap
instead by using the addition <tt><b>FT_LOAD_MONOCHROME</b></tt>
load flag.
</p></li>
</ul>
@ -857,7 +874,7 @@
FT_Set_Transform( face, &matrix, &pen );
// load glyph image into the slot (erase previous one)
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER | FT_LOAD_ANTI_ALIAS );
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
if (error) continue; // ignore errors
// now, draw to our target surface (convert position)
@ -909,6 +926,9 @@
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>
<h3>

1399
docs/tutorial/step2.html Normal file

File diff suppressed because it is too large Load Diff