ref: 1e536983f6ca0a0a684bea5c1d9255232386d293
parent: 521a2d7a13afd210283a8e071b44a881ed9bc38f
author: David Turner <[email protected]>
date: Fri Mar 23 06:20:35 EST 2001
removed obsolete documentation files they are now moved to the "www" module, under "www/freetype2/docs"
--- a/docs/cache/cache.txt
+++ /dev/null
@@ -1,267 +1,0 @@
- The FreeType 2 cache sub-system explained
- (c) 2000 David Turner
-
- -----------------------------------------------
-
-Introduction :
---------------
-
- this document describes the caching sub-system that comes
- with the FreeType library, version 2.0. Note that unlike
- the rest of the library, this code is still in beta stage
- and might still suffer slight changes in the future.
-
- Its basic design shouldn't evolve though and is explained
- in this paper.
-
-
-I. Requirements and Design Goals:
----------------------------------
-
- The FT2 cache sub-system was designed to implement caching
- of glyph images. However, it is extremely flexible and can
- be easily extended to cache other kind of data like metrics,
- character maps, coverage tables, etc..
-
-
-II. Base Concepts:
-------------------
-
- 1. The cache manager object:
-
- at the heart of the caching sub-system is a single object
- called the "cache manager". It is used to deal with FT_Face
- and FT_Size objects, as well as to manager a LRU list of
- abstract "cache nodes".
-
- a. caching FT_Face and FT_Size objects:
-
- each FT_Face object created by FreeType 2 can take from
- a few hundred bytes to several tens of kilobytes, depending
- on the original font's file format as well as its content.
-
- there is no easy way to compute the size of a given FT_Face
- object, so it's always a good idea to assume that it is
- large and to want to limit the number of live face objects
- as much as possible.
-
- similarly, each FT_Face can have one or more FT_Size childs,
- whose byte size depends heavily on the font format.
-
- the first purpose of the cache manager is to provide a
- small cache for FT_Face and FT_Size objects. Basically,
- an application can use it as follows:
-
- - each font face is described to the cache manager
- through a typeless pointer, called a FTC_FaceID.
-
- the cache manager itself doesn't interpret or use
- the value of FTC_FaceIDs directly. Rather, it passes
- them to a user-provided function called a
- "face requester". see the defintion of the
- FTC_Face_Requester type in <freetype/ftcache.h>
- for details..
-
- the face requester is in charge of translating a given
- face into into a real new FT_Face object that is
- returned to the cache manager. The latter will keep
- the face object alive as long as it needs to.
-
- the face requester is unique and must be passed
- to the function named FTC_Manager_New used to
- create/initialise a new cache manager.
-
-
- - to lookup a given FT_Face, call the function
- FTC_Manager_Lookup_Face as in the following code:
-
- FTC_Manager_Lookup_Face( manager,
- face_id,
- &face );
-
- if the corresponding FT_Face object is kept in
- the cache manager's list, it will be returned
- directly. Otherwise, this function will call
- the user-provided face requester to create
- a new FT_Face object, add it to the manager's
- list to finally return it.
-
- FT_Face objects are always destroyed by the cache
- manager. An application that uses the cache
- sub-system should never call FT_Done_Face !!
-
- - to lookup a given FT_Size and FT_Face, call the
- function FTC_Manager_Lookup_Size, as in:
-
- FTC_Manager_Lookup_Size( manager,
- ftc_font,
- &face,
- &size );
-
- where "ftc_font" is a pointer to a FTC_Font descriptor
- (a structure containing a FTC_FaceIDs and character
- dimensions corresponding to the desired FT_Size).
-
- note that the function returns both a FT_Face and
- a FT_Size object. You don't need to call
- FTC_Manager_Lookup_Face before it !!
-
- also note that returned FT_Size objects are always
- destroyed by the cache manager. A client application
- that uses it should never call FT_Done_Size !!
-
-
- the big advantage of using FTC_FaceIDs is that is
- makes the caching sub-system completely independent
- of the way font files are installed / listed / managed
- in your application. In most implementations, a FTC_FaceID
- is really a pointer to an application-specific structure
- that describe the source font file + face index.
-
-
- b - manage a MRU list of abstract "cache nodes":
-
- the second role of the cache manager is to hold and manager
- a list of abstract "cache nodes". The list is always sorted
- in most-recently-used order. The manager always ensure that
- the total size of nodes in memory doesn't over-reach a
- certain threshold, by eliminating "old" nodes when
- necessary.
-
- the cache manager doesn't know much about the cache nodes:
-
- - it knows how to move them in its list
- - it knows how to destroy them when they're too old
- - it knows how to "size" them (i.e. compute their byte
- size in memory)
-
-
- 2. Cache objects:
-
- the cache manager doesn't create new cache nodes however, this
- is the charge of what are called "cache objects".
-
- Basically, each cache object is in charge of managing cache
- nodes of a certain type. Its role is to:
-
- - provide a simple description of its cache nodes to the
- manager (i.e. through a FTC_CacheNode_Class structure)
-
- - provide a high-level API that can be called by client
- applications to lookup cache nodes of the corresponding
- type.
-
- this function usually creates new nodes when they're not
- available yet.
-
- - also, and even though this is completely transparent to
- the applications and the cache manager, each cache object
- manages "node sets", where each set contains cache nodes
- usually correspond to the same font face + font size.
-
-
- For example, the cache sub-system currently comes with two
- distinct cache classes:
-
- - a FTC_Image_Cache, which is used to cache FT_Glyph images
- (with one FT_Glyph per cache node).
-
-
- - a FTC_SBit_Cache, which is used to cache small glyph bitmaps
- ("sbit" means "embedded bitmaps" in digital typography).-
-
- the small bitmaps glyph is useful because storing one glyph
- image per cache node isn't memory efficient when the data
- associated to each node is very small. Indeed, each cache
- node has a minimal size of 20 bytes, which is huge when
- your data is an 8x8 monochrome bitmap :-)
-
- Hence, a FTC_SBit_Cache is capable of storing several
- contiguous sbits in a single cache node, resulting in much
- higher cached glyphs / total cache size.
-
- an application can lookup a FT_Glyph image with a FTC_Image_Cache
- by calling:
-
- error = FTC_Image_Cache_Lookup( image_cache,
- ftc_font,
- glyph_index,
- &ft_glyph );
-
- or a FTC_SBit (small bitmap descriptor) by calling:
-
- error = FTC_SBit_Cache_Lookup( sbit_cache,
- ftc_font,
- glyph_index,
- &ftc_sbit );
-
-III. Extending the cache sub-system:
-
- It is possible to extend the current cache sub-system by
- providing your own cache class and register it in the cache
- manager. That might be useful to cache other kind of data
- in the sub-system, like glyph metrics (without images),
-
- To do it, you'll need to read the cache sub-system public
- header files rather heavily :-) Fortunately, they're pretty
- well commented and should guide you to your goal.
-
- Note that the cache sub-system already provides two "abstract
- cache" classes that can be re-used by your own implementation:
-
-
- 1. The abstract "FTC_GlyphCache" class:
-
- this code is used to implement an abstract "glyph cache",
- i.e. one that simply maps one glyph data per cache node.
-
- it is sub-classed by FTC_Image_Cache, whose implementation
- only consists in simple code to store a FT_Glyph in each
- cache node.
-
- you could sub-class it in your application to store glyph
- images in a different format, for example.
-
- see the files <freetype/cache/ftcglyph.h> and
- "src/cache/ftcglyph.h" for details.
-
-
- 2. The abstract "FTC_ChunkCache" class:
-
- this code is used to implement an abstract "glyph chunk cache".
- it's very similar to a FTC_GlyphCache, except that it is capable
- of storing several glyph-specific elements per cache node.
-
- it is sub-classed by FTC_SBit_Cache, whose implementation
- only consists in code to store a FTC_SBitRec record in each
- node element.
-
- you could sub-class it in your application to store small
- glyph data, like metrics, glyph names, wathever.
-
- see the files <freetype/cache/ftcchunk.h> and
- "src/cache/ftcchunk.h" for details..
-
-
- Note that the two abstract caches are rather complex because
- they use "glyph sets". Each glyph set corresponds to a single
- font face + font size combination. both caches are also
- glyph-specific, though it is perfectly possible to use
- broader selection criterion, here are a few examples:
-
- - caching language coverage maps corresponding to
- a given font face + language combination
-
- - caching charmaps, layout tables, and other global
- data..
-
- - caching (font_face + font_size) specific "latin1"
- ascender + descender
-
-
- as you can see, a lot is possible with this design :-)
-
-
-
-
--- a/docs/convntns.txt
+++ /dev/null
@@ -1,710 +1,0 @@
-
- Conventions and Design in the FreeType 2 library
- ------------------------------------------------
-
-
-Table of Contents
-
-Introduction
-
-I. Style and Formatting
-
- 1. Naming
- 2. Declarations & Statements
- 3. Blocks
- 4. Macros
- 5. Conventions
-
-II. Design conventions
-
- 1. Modularity and Components Layout
- 2. Configuration and Debugging
-
-III. Usage conventions
-
- 1. Error handling
- 2. Font File I/O
- 3. Memory management
- 4. Support for threaded environments
- 5. Object Management
-
-
-
-Introduction
-============
-
-This text introduces the many conventions used within the FreeType 2
-library code. Please read it before trying any modifications or
-extensions of the source code.
-
-
-
-I. Style and Formatting
-=======================
-
-The following coding rules are extremely important to keep the
-library's source code homogeneously. Keep in mind the following
-points:
-
- - `Humans read source code, not machines' (Donald Knuth)
-
- The library source code should be as readable as possible, even
- by non-C experts. With `readable', two things are meant: First,
- the source code should be pleasant to the eye, with sufficient
- whitespace and newlines, to not look like a boring stack of
- characters stuck to each other. Second, the source should be
- _expressive_ enough about its goals. This convention contains
- rules that can help the source focus on its purpose, not on a
- particular implementation.
-
- - `Paper is the _ultimate_ debugger' (David Turner :-)
-
- There is nothing like sheets of paper (and a large floor) to
- help you understand the design of a library you're new to, or to
- debug it. The formatting style presented here is targeted at
- printing. For example, it is more than highly recommended to
- never produce a source line that is wider than 78 columns. More
- on this below.
-
-
-1. Naming
----------
-
- a. Long and expressive labels
-
- Never hesitate to use long labels for your types, variables,
- etc.! Except maybe for things like very trivial types, the
- longest is the best, as it increases the source's
- _expressiveness_. Never forget that the role of a label is to
- express the `function' of the entity it represents, not its
- implementation!
-
- NOTE: Hungarian notation is NOT expressive, as it sticks the
- `type' of a variable to its name. A label like `usFoo'
- rarely tells the use of the variable it represents.
-
- And the state of a variable (global, static, dynamic)
- isn't helpful anymore.
-
- Conclusion: Avoid Hungarian Notation in FreeType 2.
-
-
- When forging a name with several nouns
- (e.g. `number-of-points'), use an uppercase letter for the first
- letter of each word (except the first), like:
-
- numberOfPoints
-
- You are also welcome to introduce underscores `_' in your
- labels, especially when sticking large nouns together, as it
- `airs' the code greatly. E.g.:
-
- `numberOfPoints' or `number_Of_Points'
-
- `IncredibleFunction' or `Incredible_Function'
-
- And finally, always put a capital letter after an underscore,
- except in variable labels that are all lowercase:
-
- `number_of_points' is OK for a variable (_all_ lowercase label)
-
- `incredible_function' is NOT for a function!
- ^ ^
-
- `Microsoft_windows' is a *shame*!
- ^ ^
-
- `Microsoft_Windows' isn't really better, but at least its a
- ^ ^ correct function label within this
- convention ;-)
-
- b. Data types
-
- Try to use C types to the very least! Rely on internally
- defined equivalent types instead. For example, not all
- compilers agree on the sign of `char'; the size of `int' is
- platform-specific, etc.
-
- There are equivalents to the most common types in the
- `fttypes.h' public header file, like `FT_Short', `FT_UShort',
- etc. Using the internal types will guarantee that you won't
- need to replace every occurence of `short' or whatever when
- compiling on a weird platform or with a weird compiler, and
- there are many more than you could think of...
-
- c. Functions
-
- The name of a function should always begin with a capital
- letter, as lowercase first letters are reserved for variables.
- The name of a function should be, again, _expressive_! Never
- hesitate to put long function names in your code: It will make
- the code much more readable.
-
- Expressiveness doesn't necessarily imply lengthiness though; for
- instance, reading various data types from a file stream is
- performed using the following functions defined in the
- `ftstream.c' file of the `base' module:
-
- FT_Get_Char(), FT_Get_Short(), FT_Get_Long(), etc.
-
- Which is somewhat more readable than:
-
- cget, sget, usget, lget, etc.
-
- d. Variables
-
- Variable names (at least meant for the public interface) should
- always begin with a lowercase letter. Lowercase first letters
- are reserved for variables in this convention, as it has been
- already explained above. You are still welcome to use long and
- expressive variable names.
-
- Something like `numP' can express a number of pixels, porks,
- pancakes, and much more... Something like `num_points' won't.
-
- Unfortunately (mostly due to the lazyness of the developers),
- short variable names are still used in many parts of the
- library. Volunteers are highly welcome to improve this...
-
- As a side note, a field name of a structure counts as a variable
- name too.
-
-
-2. Declarations & Statements
-----------------------------
-
- Try to align declarations and assignments in columns, if it proves
- logically. For example (taken from `ttraster.c'):
-
- struct TProfile_
- {- FT_F26Dot6 X; /* current coordinate during sweep */
- PProfile link; /* link to next profile - various purpose */
- PLong offset; /* start of profile's data in render pool */
- Int flow; /* profile orientation: asc/descending */
- Long height; /* profile's height in scanlines */
- Long start; /* profile's starting scanline */
-
- UShort countL; /* number of lines to step before this */
- /* profile becomes drawable */
-
- PProfile next; /* next profile in same contour, used */
- /* during drop-out control */
- };
-
- instead of
-
- struct TProfile_
- {- FT_F26Dot6 X; /* current coordinate during sweep */
- PProfile link; /* link to next profile - various purpose */
- PLong offset; /* start of profile's data in render pool */
- Int flow; /* profile orientation: asc/descending */
- Long height; /* profile's height in scanlines */
- Long start; /* profile's starting scanline */
- UShort countL; /* number of lines to step before this */
- /* profile becomes drawable */
- PProfile next; /* next profile in same contour, used */
- /* during drop-out control */
- };
-
- This comes from the fact that you are more interested in the field
- and its function than in its type.
-
- Or:
-
- x = i + 1;
- y += j;
- min = 100;
-
- instead of
-
- x=i+1;
- y+=j;
- min=100;
-
- And don't hesitate to separate blocks of declarations with
- newlines to `distinguish' logical sections.
-
- E.g., taken from an old source file, in the declarations of the
- CMap loader:
-
- long n, num_SH;
- unsigned short u;
- long off;
- unsigned short l;
- long num_Seg;
- unsigned short* glArray;
- long table_start;
- int limit, i;
-
- TCMapDir cmap_dir;
- TCMapDirEntry entry_;
- PCMapTable Plcmt;
- PCMap2SubHeader Plcmsub;
- PCMap4 Plcm4;
- PCMap4Segment segments;
-
- instead of
-
- long n, num_SH;
- unsigned short u;
- long off;
- unsigned short l;
- long num_Seg;
- unsigned short *glArray;
- long table_start;
- int limit, i;
- TCMapDir cmap_dir;
- TCMapDirEntry entry_;
- PCMapTable Plcmt;
- PCMap2SubHeader Plcmsub;
- PCMap4 Plcm4;
- PCMap4Segment segments;
-
-
-3. Blocks
----------
-
- Block separation is done with `{' and `}'. We do not use the K&R- convention which becomes only useful with an extensive use of
- tabs. The `{' and its corresponding `}' should always be on the- same column. It makes it easier to separate a block from the rest
- of the source, and it helps your _brain_ associate the accolades
- easily (ask any Lisp programmer on the topic!).
-
- Use two spaces for the next indentation level.
-
- Never use tabs in FreeType 2 code; their widths may vary with
- editors and systems.
-
- Example:
-
- if (condition_test) {- waow mamma;
- I'm doing K&R format;
- just like the Linux kernel;
- } else {- This test failed poorly;
- }
-
- should be rather formatted as
-
- if ( condition_test )
- {- This code isn't stuck to the condition;
- read it on paper, you will find it more;
- pleasant to the eye;
- }
- else
- {- Of course, this is a matter of taste;
- This is just the way it is in this convention;
- and you should follow it to be homogenuous with;
- the rest of the FreeType code;
- }
-
-
-4. Macros
----------
-
- Macros should be made of uppercase letters. If a macro label is
- forged from several words, it is possible to only uppercasify the
- first word, using an underscore to separate the nouns. This is
- used in in some files for macros like
-
- GET_UShort(), USE_Stream(), etc.
-
- The role of macros used throughout the engine is explained later
- in this document.
-
-
-5. Conventions
---------------
-
- Currently, FreeType 2 source code uses the following formatting
- rules:
-
- . The data type is separated with two spaces from the variable,
- structure, or function name:
-
- const char foo;
-
- Usually, the `*' operator is concatenated to the data type:
-
- FT_Int* pointer;
-
- However, when declaring resp. defining an `output' parameter
- (i.e. a pointer which will be assigned by the function), the
- last `*' must be placed on the right in order to denote this, as
- in:
-
- FT_New_Face( FT_Library library,
- FT_Face *aface );
-
- where the `*' is used to indicate that `aface' is returned. In
- most cases, the name of such an output variable starts with `a'
- or `an' (`aface' instead of `face', `anlru' instead of `lru',
- etc.), following the English rules of the indefinite article.
-
- . As mentioned above, multiple declarations are vertically
- aligned:
-
- FT_Short foo;
- FT_Long bar;
- FT_GlyphSlot slot;
-
- . Declarations are separated with two blank lines from the
- following code. This intentionally disturbs the code flow to
- make variable definitions more visible.
-
- {- char x, y;
-
-
- x = 3;
- y = 5;
- }
-
- . An opening parenthesis follows a function directly without
- space; after a built-in C keyword, one space is used:
-
- x = sin( y );
- y = sizeof ( long );
-
- Except for casts, empty parameters, and the closing semicolon,
- parentheses are surrounded with space:
-
- x = (char*)( foo + bar );
- y = rand();
-
- . Binary operators are surrounded by spaces; unary operators have
- no space after it:
-
- x = ( 3 + 4 ) / ( 7 - 2 );
- y = -( 3 + 4 ) * 7;
-
- . Array arguments are not surrounded by spaces:
-
- array[3] = array[1] + array[2];
- array[4] = array[1 + 3];
-
- . Comma and semicolon have only space at the right side:
-
- if ( x = 0; x < y; x++, y-- )
- do_something();
-
- Exception:
-
- for (;;)
- {- ...
-
- . Don't use
-
- if ( x == y ) a = b;
-
- but
-
- if ( x == y )
- a = b;
-
- in general.
-
- . Preprocessor directives are never indented and always start in
- the first column.
-
- . All function/structure/variable definitions start at column
- three.
-
- . All full-line comments (except the header of a file) start at
- column three (even comments for preprocessor directives).
-
- . Labels are sticking out two positions to the left:
-
- switch ( x )
- {- case 1:
- do_something();
- break;
- default:
- do_nothing();
- break;
- }
-
-
-
-II. Design Conventions
-======================
-
-
-1. Modularity and Components Layout
------------------------------------
-
- The FreeType 2 engine has been designed with portability in mind.
- This implies the ability to compile and run it on a great variety
- of systems and weird environments, unlike many packages where the
- word strictly means `runs on a bunch of Unix-like systems'. We
- have thus decided to stick to the following restrictions:
-
- - The C version is written entirely in ANSI C.
-
- - The library, if compiled with gcc, doesn't produce any warning
- with the `-ansi -pedantic' flags. Other compilers with better
- checks may produce ANSI warnings -- please report.
-
- (NOTE: It can of course be compiled by an `average' C compiler,
- and even by a C++ one.)
-
- - It only requires in its simplest form an ANSI libc to compile,
- and no utilities other than a C preprocessor, compiler, and
- linker.
-
- - It consists of modules, starting with a `base' module which
- provides the API, some auxiliary modules used by the font
- drivers, the font driver modules itself, and the rasterizer
- modules.
-
- - The very low-level components can be easily replaced by
- system-specific ones that do not rely on the standard libc.
- These components deal mainly with i/o, memory, and mutex
- operations.
-
- - A client application only needs to include one header file named
- `freetype.h' to use the engine. Other public header files like
- `ftglyph.h' or `ftimage.h' provide functional extensions.
-
- - All configuration options are gathered in two files,
- `ftconfig.h' and `ftoption.h'. The former contains the
- processor and OS specific configuration options, while the
- latter treats options that may be enabled or disabled by the
- user to enable and disable various features.
-
-
-2. Configuration and Debugging
-------------------------------
-
- Configuration is covered by the `BUILD' documentation file.
-
- Debugging is controlled by two macros in `ftoption.h',
- FT_DEBUG_LEVEL_ERROR and FT_DEBUG_LEVEL_TRACE; don't use them in
- code to be released. Check the source code of the `ftview.c'
- demonstration program (in the `ft2demos' package) how tracing can
- be used and activated.
-
-
-
-III. Usage conventions
-======================
-
-
-1. Error Handling
------------------
-
- Most functions directly return an error code. A return value of 0
- (FT_Err_Ok) means that no error occured, while a non-zero other
- value indicates a failure of any kind.
-
- We use code like this in FreeType 2:
-
- if ( ( rc = Perform_Action_1( parms_of_1 ) ) ||
- ( rc = Perform_Action_2( parms_of_2 ) ) ||
- ( rc = Perform_Action_3( parms_of_3 ) ) )
- goto Fail;
-
- which is better but uses assignments within expressions, which are
- always delicate to manipulate in C (the risk of writing `=='
- exists, and would go unnoticed by a compiler). Moreover, the
- assignments are a bit redundant and don't express much things
- about the actions performed (they only speak of the error
- management issue).
-
- That is why some macros have been defined for the most frequently
- used functions. They relate to low-level routines that are called
- very often (mainly i/o and memory handling functions). Each macro
- produces an implicit assignment to a variable called `error' and
- can be used instead as a simple function call. Example:
-
- if ( PERFORM_Action_1( parms_of_1 ) ||
- PERFORM_Action_2( parms_of_2 ) ||
- PERFORM_Action_3( parms_of_3 ) )
- goto Fail;
-
- with
-
- #define PERFORM_Action_1( parms_1 ) \
- ( error = Perform_Action_1( parms_1 ) )
- #define PERFORM_Action_2( parms_1 ) \
- ( error = Perform_Action_2( parms_1 ) )
- #define PERFORM_Action_3( parms_1 ) \
- ( error = Perform_Action_3( parms_1 ) )
-
- defined in some header file.
-
- There, the developer only needs to define a local `error' variable
- and use the macros directly in the code, without caring about the
- actual error handling performed. Another advantage is that the
- structure of source files remain very similar, even though the
- error handling may be different.
-
- This convention is very close to the use of exceptions in
- languages like C++, Pascal, Java, etc. where the developer
- focuses on the actions to perform, and not on every little error
- checking.
-
-
-2. Font File I/O
-----------------
-
- a. Streams
-
- The engine uses `streams' to access the font files. A stream is
- a structure containing information used to access files through
- a system-specific i/o library.
-
- The default implementation of streams uses the ANSI libc i/o
- functions. However, for the sake of embedding in light systems
- and independence of a complete C library, it is possible to
- re-implement the component for a specific system or OS, letting
- it use system calls.
-
- b. Frames
-
- TrueType is tied to the big-endian format, which implies that
- reading shorts or longs from the font file may need conversions
- depending on the target processor. To be able to easily detect
- read errors and allow simple conversion calls or macros, the
- engine is able to access a font file using `frames'.
-
- A frame is simply a sequence of successive bytes taken from the
- input file at the current position. A frame is pre-loaded into
- memory by a call to the `ACCESS_Frame()' macro.
-
- It is then possible to read all sizes of data through the
- `GET_xxx()' macros described above.
-
- When all important data is read, the frame can be released by a
- call to `FORGET_Frame()'.
-
- The benefits of frames are various. Consider these two
- approaches at extracting values:
-
- if ( ( error = Read_Short( &var1 ) ) ||
- ( error = Read_Long ( &var2 ) ) ||
- ( error = Read_Long ( &var3 ) ) ||
- ( error = Read_Short( &var4 ) ) )
-
- return FAILURE;
-
- and
-
- /* Read the next 16 bytes */
- if ( ACCESS_Frame( 16L ) )
- return error; /* The Frame could not be read */
-
- var1 = GET_Short(); /* extract values from the frame */
- var2 = GET_Long();
- var3 = GET_Long();
- var4 = GET_Short();
-
- FORGET_Frame(); /* release the frame */
-
- In the first case, there are four error assignments with four
- checks of the file read. This unnecessarily increases the size
- of the generated code. Moreover, you must be sure that `var1'
- and `var4' are short variables, `var2' and `var3' long ones, if
- you want to avoid bugs and/or compiler warnings.
-
- In the second case, you perform only one check for the read, and
- exit immediately on failure. Then the values are extracted from
- the frame, as the result of function calls. This means that you
- can use automatic type conversion; there is no problem if
- e.g. `var1' and `var4' are longs, unlike previously.
-
- Finally, frames are ideal when you are using memory-mapped
- files, as the frame is not really `pre-loaded' and never uses
- any `heap' space.
-
- IMPORTANT: You CANNOT nest several frame accesses. There is
- only one frame available at a time for a specific
- instance.
-
- It is also the programmer's responsibility to never
- extract more data than was pre-loaded in the frame!
- (But you usually know how many values you want to
- extract from the file before doing so).
-
-
-3. Memory Management
---------------------
-
- The library now has a component which uses an interface similar to
- malloc()/free().
-
- * FT_Alloc()
-
- To be used like malloc(), except that it returns an error code,
- not an address. Its arguments are the size of the requested
- block and the address of the target pointer to the `fresh'
- block. An error code is returned in case of failure (and this
- will also set the target pointer to NULL), 0 in case of success.
-
- FT_Alloc() internally calls the ft_alloc() function defined in
- an FT_Memory object. All error checking is done by FT_Alloc()
- itself so that ft_alloc() directly calls malloc().
-
- * FT_Realloc()
-
- Similar to FT_Alloc(); it calls realloc() by default.
-
- * FT_Free()
-
- As you may have already guessed, FT_Free() is FT_Alloc()'s
- counterpart. It takes as argument the _target pointer's
- address_! You should _never_ pass the block's address directly,
- i.e. the pointer, to FT_Free().
-
- Similar to FT_Alloc(), FT_Free() does the necessary error
- checking and calls free() by default.
-
- As the pointers addresses needed as arguments are typed `void**',
- ftmemory.h provides some macros to help use the above functions
- more easily, these are:
-
- MEM_Alloc() A version of FT_Alloc() that casts the argument
- pointer to (void**). Similar functions are
- MEM_Alloc_Array(), MEM_Realloc(), and
- MEM_Realloc_Array()
-
- ALLOC() Same as MEM_Alloc(), but with an assignment to a
- variable called `error'. See the section `error
- handling' above for more info on this. Similar
- functions are REALLOC(), ALLOC_ARRAY(), and
- REALLOC_ARRAY().
-
- FREE() A version of FT_Free() that casts the argument
- pointer to (void**).
-
- MEM_Set() An alias for `memset()', which can be easily
- changed to anything else if you wish to use a
- different memory manager than the functions
- provided by the ANSI libc.
-
- MEM_Copy() An alias of `memcpy()' or `bcopy()' used to move
- blocks of memory. You may change it to something
- different if necessary (e.g. not using libc).
-
- MEM_Move() An alias of `memmove().' Change its definition if
- necessary.
-
-
-4. Support for threaded environments
-------------------------------------
-
- Thread synchronisation has been dropped in FreeType 2. The
- library is already re-entrant, and if you really need two threads
- accessing the same FT_Library object, you should synchronize
- access to it yourself with a simple mutex.
-
-
---- end of convntns.txt ---
binary files a/docs/design/basic-design.png /dev/null differ
--- a/docs/design/design-1.html
+++ /dev/null
@@ -1,160 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
-
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-2.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#ccccee"><td>
- <h1>
- Introduction
- </h1>
- </td></tr>
- </table>
-
- <p>This document provides details on the design and implementation of the
- FreeType 2 library. Its goal is to allow developers to better
- understand the way how FreeType 2 is organized, in order to let them
- extend, customize, and debug it.</p>
-
- <p>Before anything else, it is important to understand the
- <em>purpose</em> of this library, i.e., why it has been written:</p>
-
- <ul>
- <li>
- <p>It allows client applications to <em>access font files easily</em>,
- wherever they could be stored, and as independently of the font format
- as possible.</p>
- </li>
- <li>
- <p>Easy <em>retrieval of global font data</em> most commonly found in
- normal font formats (i.e. global metrics, encoding/charmaps,
- etc.).</p>
- </li>
- <li>
- <p>It allows easy <em>retrieval of individual glyph data</em>
- (metrics, images, name, anything else).</p>
- </li>
- <li>
- <p><em>Access to font format-specific "features"</em> whenever
- possible (e.g. SFNT tables, Multiple Masters, OpenType Layout tables,
- etc.).</p>
- </li>
- </ul>
-
- <p>Its design has also severely been influenced by the following
- requirements:</p>
-
- <ul>
- <li>
- <p><em>High portability</em>. The library must be able to run on any
- kind of environment. This requirement introduces a few drastic
- choices that are part of FreeType 2's low-level system
- interface.</p>
- </li>
- <li>
- <p><em>Extendability</em>. New features should be added with the
- least modifications in the library's code base. This requirement
- induces an extremely simple design where nearly all operations are
- provided by modules.</p>
- </li>
- <li>
- <p><em>Customization</b>. It should be easy to build a version of the
- library that only contains the features needed by a specific project.
- This really is important when you need to integrate it in a font
- server for embedded graphics libraries.</p>
- </li>
- <li>
- <p><em>Compactness</em> and <em>efficiency</em>. The primary target
- for this library are embedded systems with low cpu and memory
- resources.</p>
- </li>
- </ul>
-
- <p>The rest of this document is divided in several sections. First, a few
- chapters will present the library's basic design as well as the
- objects/data managed internally by FreeType 2.</p>
-
- <p>A later section is then dedicated to library customization, relating
- such topics as system-specific interfaces, how to write your own module
- and how to tailor library initialization & compilation to your needs.</p>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
-
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-3.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/design/design-2.html
+++ /dev/null
@@ -1,187 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="design-1.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-3.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#ccccee"><td>
- <h1>
- I. Components and APIs
- </h1>
- </td></tr>
- </table>
-
- <p>It's better to describe FreeType 2 as a collection of
- <em>components</em>. Each one of them is a more or less abstract part of
- the library that is in charge of one specific task. We will now explicit
- the connections and relationships between them.</p>
-
- <p>A first brief description of this system of components could be:</p>
-
- <ul>
- <li>
- <p>Client applications typically call the FreeType 2
- <b>high-level API</b>, whose functions are implemented in a single
- component called the <em>Base Layer</em>.</p>
- </li>
- <li>
- <p>Depending on the context or the task, the base layer then calls one
- or more <em>module</em> components to perform the work. In most
- cases, the client application doesn't need to know which module was
- called.</p>
- </li>
- <li>
- <p>The base layer also contains a set of routines that are used for
- generic things like memory allocation, list processing, i/o stream
- parsing, fixed point computation, etc. these functions can also be
- called by a module at any time, and they form what is called the
- <b>low-level base API</b>.</p>
- </li>
- </ul>
-
- <p>This is illustrated by the following graphics (note that component
- entry points are represented as colored triangles):</p>
-
- <center>
- <img src="basic-design.png"
- width="394" height="313"
- alt="Basic FreeType design">
- </center>
-
- <p>Now, a few additional things must be added to complete this
- picture:</p>
-
- <ul>
- <li>
- <p>Some parts of the base layer can be replaced for specific builds of
- the library, and can thus be considered as components themselves.
- This is the case for the <tt>ftsystem</tt> component, which is in
- charge of implementing memory management & input stream access, as
- well as <tt>ftinit</tt>, which is in charge of library initialization
- (i.e. implementing the <tt>FT_Init_FreeType()</tt> function).</p>
- </li>
- <li>
- <p>FreeType 2 comes also with a set of <em>optional
- components</em>, which can be used either as a convenience for client
- applications (e.g. the <tt>ftglyph</tt> component, used to provide a
- simple API to manage glyph images independently of their internal
- representation), or to access format-specific features (e.g. the
- <tt>ftmm</tt> component used to access and manage Multiple Masters
- data in Type 1 fonts).</p>
- </li>
- <li>
- <p>Finally, a module is capable of calling functions provided by
- another module. This is very useful to share code and tables between
- several font driver modules (for example, the <tt>truetype</tt> and
- <tt>cff</tt> modules both use the routines provided by the
- <tt>sfnt</tt> module).</p>
- </li>
- </ul>
-
- <p>Hence, a more complete picture would be:</p>
-
- <center>
- <img src="detailed-design.png"
- width="390" height="429"
- alt="Detailed FreeType design">
- </center>
-
- <p>Please take note of the following important points:</p>
-
- <ul>
- <li>
- <p>An optional component can use either the high-level or base API.
- This is the case of <tt>ftglyph</tt> in the above picture.</p>
- </li>
- <li>
- <p>Some optional components can use module-specific interfaces ignored
- by the base layer. In the above example, <tt>ftmm</tt> directly
- accesses the Type 1 module to set/query data.</p>
- </li>
- <li>
- <p>A replacable component can provide a function of the high-level
- API. For example, <tt>ftinit</tt> provides
- <tt>FT_Init_FreeType()</tt> to client applications.</p>
- </li>
- </ul>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
- <a href="design-1.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-3.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/design/design-3.html
+++ /dev/null
@@ -1,353 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="design-2.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-4.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#ccccee"><td>
- <h1>
- II. Public Objects and Classes
- </h1>
- </td></tr>
- </table>
-
- <p>We will now explain the abstractions provided by FreeType 2 to
- client applications to manage font files and data. As you would normally
- expect, these are implemented through objects/classes.</p>
-
- <h2>
- 1. Object Orientation in FreeType 2
- </h2>
-
- <p>Though written in ANSI C, the library employs a few techniques,
- inherited from object-oriented programming, to make it easy to extend.
- Hence, the following conventions apply in the FreeType 2 source
- code:</p>
-
- <ol>
- <li>
- <p>Each object type/class has a corresponding <em>structure
- type</em> <b>and</b> a corresponding <em>structure pointer
- type</em>. The latter is called the <em>handle type</em> for the
- type/class.</p>
-
- <p>Consider that we need to manage objects of type "foo" in
- FreeType 2. We would define the following structure and handle
- types as follows:</p>
-
- <font color="blue"><pre>
- typedef struct FT_FooRec_* FT_Foo;
-
- typedef struct FT_FooRec_
- {- // fields for the "foo" class
- ...
-
- } FT_FooRec;</pre>
- </font>
-
- <p>As a convention, handle types use simple but meaningful
- identifiers beginning with <tt>FT_</tt>, as in <tt>FT_Foo</tt>,
- while structures use the same name with a <tt>Rec</tt> suffix
- appended to it ("Rec" is short for "record"). <em>Note that each- class type has a corresponding handle type</em>.</p>
- </li>
- <li>
- <p>Class derivation is achieved internally by wrapping base class
- structures into new ones. As an example, we define a "foobar" class
- that is derived from "foo". We would do something like:</p>
-
- <font color="blue"><pre>
- typedef struct FT_FooBarRec_* FT_FooBar;
-
- typedef struct FT_FooBarRec_
- {- // the base "foo" class fields
- FT_FooRec root;
-
- // fields proper to the "foobar" class
- ...
- } FT_FooBarRec;</pre>
- </font>
-
- <p>As you can see, we ensure that a "foobar" object is also a "foo"
- object by placing a <tt>FT_FooRec</tt> at the start of the
- <tt>FT_FooBarRec</tt> definition. It is called <b>root</b> by
- convention.</p>
-
- <p>Note that a <tt>FT_FooBar</tt> handle also points to a "foo"
- object and can be typecasted to <tt>FT_Foo</tt>. Similarly, when
- the library returns a <tt>FT_Foo</tt> handle to client applications,
- the object can be really implemented as a <tt>FT_FooBar</tt> or any
- derived class from "foo".</p>
- </li>
- </ol>
-
- <p>In the following sections of this chapter, we will refer to "the
- <tt>FT_Foo</tt> class" to indicate the type of objects handled through
- <tt>FT_Foo</tt> pointers, be they implemented as "foo" or "foobar".</p>
-
- <hr>
-
- <h2>
- 2. The <tt>FT_Library</tt> class
- </h2>
-
- <p>This type corresponds to a handle to a single instance of the
- library. Note that the corresponding structure <tt>FT_LibraryRec</tt>
- is not defined in public header files, making client applications unable
- to access its internal fields.</p>
-
- <p>The library object is the <em>parent</em> of all other objects in
- FreeType 2. You need to create a new library instance before doing
- anything else with the library. Similarly, destroying it will
- automatically destroy all its children (i.e. faces and modules).</p>
-
- <p>Typical client applications should call <tt>FT_Init_FreeType()</tt>
- in order to create a new library object, ready to be used for further
- actions.</p>
-
- <p>Another alternative is to create a fresh new library instance by
- calling the function <tt>FT_New_Library()</tt>, defined in the
- <tt><freetype/ftmodule.h></tt> public header file. This function
- will however return an "empty" library instance with no module
- registered in it. You can "install" modules in the instance by calling
- <tt>FT_Add_Module()</tt> manually.</p>
-
- <p>Calling <tt>FT_Init_FreeType()</tt> is a lot more convenient, because
- this function basically registers a set of default modules into each new
- library instance. The way this list is accessed and/or computed is
- determined at build time, and depends on the content of the
- <tt>ftinit</tt> component. This process is explained in details later
- in this document.</p>
-
- <p>For now, one should consider that library objects are created with
- <tt>FT_Init_FreeType()</tt>, and destroyed along with all children with
- <tt>FT_Done_FreeType()</tt>.</p>
-
- <hr>
-
- <h2>
- 3. The <tt>FT_Face</tt> class
- </h2>
-
- <p>A face object corresponds to a single <em>font face</em>, i.e., a
- specific typeface with a specific style. For example, "Arial" and
- "Arial Italic" correspond to two distinct faces.</p>
-
- <p>A face object is normally created through <tt>FT_New_Face()</tt>.
- This function takes the following parameters: an <tt>FT_Library</tt>
- handle, a C file pathname used to indicate which font file to open, an
- index used to decide which face to load from the file (a single file may
- contain several faces in certain cases), and the address of a
- <tt>FT_Face</tt> handle. It returns an error code:</p>
-
- <font color="blue"><pre>
- FT_Error FT_New_Face( FT_Library library,
- const char* filepathname,
- FT_Long face_index,
- FT_Face* face );</pre>
- </font>
-
- <p>In case of success, the function will return 0, and the handle
- pointed to by the <tt>face</tt> parameter will be set to a non-NULL
- value.</p>
-
- <p>Note that the face object contains several fields used to describe
- global font data that can be accessed directly by client applications.
- For example, the total number of glyphs in the face, the face's family
- name, style name, the EM size for scalable formats, etc. For more
- details, look at the <tt>FT_FaceRec</tt> definition in the
- FreeType 2 API Reference.</p>
-
- <hr>
-
- <h2>
- 4. The <tt>FT_Size</tt> class
- </h2>
-
- <p>Each <tt>FT_Face</tt> object <em>has</em> one or more
- <tt>FT_Size</tt> objects. A <em>size object</em> is used to store data
- specific to a given character width and height. Each newly created face
- object has one size, which is directly accessible as
- <tt>face->size</tt>.</p>
-
- <p>The contents of a size object can be changed by calling either
- <tt>FT_Set_Pixel_Sizes()</tt> or <tt>FT_Set_Char_Size()</tt>.</p>
-
- <p>A new size object can be created with <tt>FT_New_Size()</tt>, and
- destroyed manually with </tt>FT_Done_Size()</tt>. Note that typical
- applications don't need to do this normally: they tend to use the
- default size object provided with each <tt>FT_Face</tt>.</p>
-
- <p>The public fields of <tt>FT_Size</tt> objects are defined in a very
- small structure named <tt>FT_SizeRec</tt>. However, it is important to
- understand that some font drivers define their own derivatives of
- <tt>FT_Size</tt> to store important internal data that is re-computed
- each time the character size changes. Most of the time, these are
- size-specific <em>font hints</em>./p>
-
- <p>For example, the TrueType driver stores the scaled CVT table that
- results from the execution of the "cvt" program in a <tt>TT_Size</tt>
- structure, while the Type 1 driver stores scaled global metrics
- (like blue zones) in a <tt>T1_Size</tt> object. Don't worry if you
- don't understand the current paragraph; most of this stuff is highly
- font format specific and doesn't need to be explained to client
- developers :-)</p>
-
- <hr>
-
- <h2>
- 5. The <tt>FT_GlyphSlot</tt> class
- </h2>
-
- <p>The purpose of a glyph slot is to provide a place where glyph images
- can be loaded one by one easily, independently of the glyph image format
- (bitmap, vector outline, or anything else).</p>
-
- <p>Ideally, once a glyph slot is created, any glyph image can be loaded
- into it without additional memory allocation. In practice, this is only
- possible with certain formats like TrueType which explicitly provide
- data to compute a slot's maximum size.</p>
-
- <p>Another reason for glyph slots is that they are also used to hold
- format-specific hints for a given glyphs as well as all other data
- necessary to correctly load the glyph.</p>
-
- <p>The base <tt>FT_GlyphSlotRec</tt> structure only presents glyph
- metrics and images to client applications, while actual implementation
- may contain more sophisticated data.</p>
-
- <p>As an example, the TrueType-specific <tt>TT_GlyphSlotRec</tt>
- structure contains additional fields to hold glyph-specific bytecode,
- transient outlines used during the hinting process, and a few other
- things.
-
- The Type 1-specific <tt>T1_GlyphSlotRec</tt> structure holds glyph
- hints during glyph loading, as well as additional logic used to properly
- hint the glyphs when a native Type 1 hinter is used.</p>
-
- <p>Finally, each face object has a single glyph slot that is directly
- accessible as <tt>face->glyph</tt>.</p>
-
- <hr>
-
- <h2>
- 6. The <tt>FT_CharMap</tt> class
- </h2>
-
- <p>The <tt>FT_CharMap</tt> type is used as a handle to character map
- objects, or <em>charmaps</em>. A charmap is simply some sort of table
- or dictionary which is used to translate character codes in a given
- encoding into glyph indices for the font.</p>
-
- <p>A single face may contain several charmaps. Each one of them
- corresponds to a given character repertoire, like Unicode, Apple Roman,
- Windows codepages, and other encodings.</p>
-
- <p>Each <tt>FT_CharMap</tt> object contains a "platform" and an
- "encoding" field used to identify precisely the character repertoire
- corresponding to it.</p>
-
- <p>Each font format provides its own derivative of
- <tt>FT_CharMapRec</tt> and thus needs to implement these objects.</p>
-
- <hr>
-
- <h2>
- 7. Objects relationships
- </h2>
-
- <p>The following diagram summarizes what we have just said regarding the
- public objects managed by the library, as well as explicitely describes
- their relationships</p>
-
- <center>
- <img src="simple-model.png"
- width=453 height=378
- alt="Simple library model">
- </center>
-
- <p>Note that this picture will be updated at the end of the next
- chapter, related to <em>internal objects</em>.</p>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
- <a href="design-2.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-4.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/design/design-4.html
+++ /dev/null
@@ -1,361 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="design-3.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-5.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#ccccee"><td>
- <h1>
- III. Internal Objects and Classes
- </h1>
- </td></tr>
- </table>
-
- <p>Let us have a look now at the <em>internal</em> objects that
- FreeType 2 uses, i.e., those not directly available to client
- applications, and see how they fit into the picture.</p>
-
- <h2>
- 1. Memory management
- </h2>
-
- <p>All memory management operations are performed through three specific
- routines of the base layer, namely: <tt>FT_Alloc()</tt>,
- <tt>FT_Realloc()</tt>, and <tt>FT_Free()</tt>. Each one of these
- functions expects a <tt>FT_Memory</tt> handle as its first
- parameter.</p>
-
- <p>The latter is a pointer to a simple object used to describe the
- current memory pool/manager. It contains a simple table of
- alloc/realloc/free functions. A memory manager is created at library
- initialization time by <tt>FT_Init_FreeType()</tt>, calling the function
- <tt>FT_New_Memory()</tt> provided by the <tt>ftsystem</tt>
- component.</p>
-
- <p>By default, this manager uses the ANSI <tt>malloc()</tt>,
- <tt>realloc()</tt>, and <tt>free()</tt> functions. However, as
- <tt>ftsystem</tt> is a replaceable part of the base layer, a specific
- build of the library could provide a different default memory
- manager.</p>
-
- <p>Even with a default build, client applications are still able to
- provide their own memory manager by not calling
- <tt>FT_Init_FreeType()</tt> but follow these simple steps:</p>
-
- <ol>
- <li>
- <p>Create a new <tt>FT_Memory</tt> object by hand. The definition
- of <tt>FT_MemoryRec</tt> is located in the public file
- <tt><freetype/ftsystem.h></tt>.</p>
- </li>
- <li>
- <p>Call <tt>FT_New_Library()</tt> to create a new library instance
- using your custom memory manager. This new library doesn't yet
- contain any registered modules.</p>
- </li>
- <li>
- <p>Register the set of default modules by calling the function
- <tt>FT_Add_Default_Modules()</tt> provided by the <tt>ftinit</tt>
- component, or manually register your drivers by repeatedly
- calling <tt>FT_Add_Module()</tt>.</p>
- </li>
- </ol>
-
- <hr>
-
- <h2>
- 2. Input streams
- </h2>
-
- <p>Font files are always read through <tt>FT_Stream</tt> objects. The
- definition of <tt>FT_StreamRec</tt> is located in the public file
- <tt><freetype/ftsystem.h></tt>, which allows client developers to
- provide their own implementation of streams if they wish so.</p>
-
- <p>The function <tt>FT_New_Face()</tt> will always automatically create
- a new stream object from the C pathname given as its second
- argument. This is achieved by calling the function
- <tt>FT_New_Stream()</tt> provided by the <tt>ftsystem</tt> component.
- As the latter is replaceable, the implementation of streams may vary
- greatly between platforms.</p>
-
- <p>As an example, the default implementation of streams is located in
- the file <tt>src/base/ftsystem.c</tt> and uses the ANSI
- <tt>fopen()</tt>, <tt>fseek()</tt>, and <tt>fread()</tt> calls.
- However, the Unix build of FreeType 2 provides an alternative
- implementation that uses memory-mapped files, when available on the host
- platform, resulting in a significant access speed-up.</p>
-
- <p>FreeType distinguishes between memory-based and disk-based streams.
- In the first case, all data is directly accessed in memory (e.g.
- ROM-based, write-only static data and memory-mapped files), while in the
- second, portions of the font files are read in chunks called
- <em>frames</em>, and temporarily buffered similarly through typical
- seek/read operations.</p>
-
- <p>The FreeType stream sub-system also implements extremely efficient
- algorithms to very quickly load structures from font files while
- ensuring complete safety in the case of a "broken file".</p>
-
- <p>The function <tt>FT_New_Memory_Face()</tt> can be used to directly
- create/open a <tt>FT_Face</tt> object from data that is readily
- available in memory (including ROM-based fonts).</p>
-
- <p>Finally, in the case where a custom input stream is needed, client
- applications can use the function <tt>FT_Open_Face()</tt>, which can
- accept custom input streams. This may be useful in the case of
- compressed or remote font files, or even embedded font files that need
- to be extracted from certain documents.</p>
-
- <p>Note that each face owns a single stream, which is also destroyed by
- <tt>FT_Done_Face()</tt>. Generally speaking, it is certainly
- <em>not</em> a good idea to keep numerous <tt>FT_Face</tt> objects
- opened.</p>
-
- <hr>
-
- <h2>
- 3. Modules
- </h2>
-
- <p>A FreeType 2 module is itself a piece of code. However, the
- library creates a single <tt>FT_Module</tt> object for each module that
- is registered when <tt>FT_Add_Module()</tt> is called.</p>
-
- <p>The definition of <tt>FT_ModuleRec</tt> is not publicly available to
- client applications. However, each <em>module type</em> is described by
- a simple public structure named <tt>FT_Module_Class</tt>, defined in
- <tt><freetype/ftmodule.h></tt>, and is described later in this
- document:</p>
-
- <p>You need a pointer to an <tt>FT_Module_Class</tt> structure when
- calling <tt>FT_Add_Module()</tt>, whose declaration is:</p>
-
- <font color="blue"><pre>
- FT_Error FT_Add_Module( FT_Library library,
- const FT_Module_Class* clazz );</pre>
- </font>
-
- <p>Calling this function will do the following:</p>
-
- <ul>
- <li>
- <p>It will check whether the library already holds a module object
- corresponding to the same module name as the one found in
- <tt>FT_Module_Class</tt>.</p>
- </li>
- <li>
- <p>If this is the case, it will compare the module version number to
- see whether it is possible to <em>upgrade</em> the module to a new
- version. If the module class's version number is smaller than the
- already installed one, the function returns immediately. Similarly,
- it checks that the version of FreeType 2 that is running is
- correct compared to the one required by the module.</p>
- </li>
- <li>
- <p>It creates a new <tt>FT_Module</tt> object, using data and flags
- of the module class to determine its byte size and how to properly
- initialize it.</p>
- </li>
- <li>
- <p>If a module initializer is present in the module class, it will
- be called to complete the module object's initialization.</p>
- </li>
- <li>
- <p>The new module is added to the library's list of "registered"
- modules. In case of an upgrade, the previous module object is
- simply destroyed.</p>
- </li>
- </ul>
-
- <p>Note that this function doesn't return an <tt>FT_Module</tt> handle,
- given that module objects are completely internal to the library (and
- client applications shouldn't normally mess with them :-)</p>
-
- <p>Finally, it is important to understand that FreeType 2
- recognizes and manages several kinds of modules. These will be
- explained in more details later in this document, but we will list for
- now the following types:</p>
-
- <ul>
- <li>
- <p><em>Renderer</em> modules are used to convert native glyph images
- to bitmaps/pixmaps. FreeType 2 comes with two renderer modules
- by default: one to generate monochrome bitmaps, the other to
- generate high-quality anti-aliased pixmaps.</p>
- </li>
- <li>
- <p><em>Font driver</em> modules are used to support one or more font
- formats. Typically, each font driver provides a specific
- implementation/derivative of <tt>FT_Face</tt>, <tt>FT_Size</tt>,
- <tt>FT_GlyphSlot</tt>, as well as <tt>FT_CharMap</tt>.</p>
- </li>
- <li>
- <p><em>Helper</em> modules are shared by several font drivers. For
- example, the <tt>sfnt</tt> module parses and manages tables found in
- SFNT-based font formats; it is then used by both the TrueType and
- OpenType font drivers.</p>
- </li>
- <li>
- <p>Finally, the <em>auto-hinter</em> module has a specific place in
- the library's design, as its role is to process vectorial glyph
- outlines, independently of their native font format, to produce
- optimal results at small pixel sizes.</p>
- </li>
- </ul>
-
- <p>Note that every <tt>FT_Face</tt> object is <em>owned</em> by the
- corresponding font driver, depending on the original font file's format.
- This means that all face objects are destroyed when a module is
- removed/unregistered from a library instance (typically by calling the
- <tt>FT_Remove_Module()</tt> function).</p>
-
- <p><em>Because of this, you should always take care that no
- <tt>FT_Face</tt> object is opened when you upgrade or remove a module
- from a library, as this could cause unexpected object deletion!</em></p>
-
- <hr>
-
- <h2>
- 4. Libraries
- </h2>
-
- <p>We now come back to our well-known <tt>FT_Library</tt> object. From
- what have been said before, we already know that a library instance owns
- at least the following:</p>
-
- <ul>
- <li>
- <p>A memory manager object (<tt>FT_Memory</tt>), used for all
- allocation/releases within the instance.</p>
- </li>
- <li>
- <p>A list of <tt>FT_Module</tt> objects, corresponding to the
- "installed" or "registered" modules of the instance. This list can
- be changed at any time through <tt>FT_Add_Module()</tt> and
- <tt>FT_Remove_Module()</tt>.</p>
- </li>
- <li>
- <p>Remember that face objects are owner by font drivers that are
- themselves modules owned by the library.</p>
- </li>
- </ul>
-
- <p>There is however another object owned by the library instance that
- hasn't been described yet: the <em>raster pool</em>.</p>
-
- <p>The <em>raster pool</em> is simply a block of memory of fixed size
- that is used internally as a "scratch area" for various memory-hungry
- transient operations, avoiding memory allocation. For example, it is
- used by each renderer when converting a vectorial glyph outline into a
- bitmap (actually, that's where its name comes from :-).</p>
-
- <p>The size of the raster pool is fixed at initialisation time (it
- defaults to 16kByte) and cannot be changed at run-time (though we could
- fix this if there is a real need for that).</p>
-
- <p>When a transient operation needs more memory than the pool's size, it
- can decide to either allocate a heap block as an exceptional condition,
- or sub-divide recursively the task to perform in order to never exceed
- the pool's threshold.</p>
-
- <p>This extremely memory-conservative behaviour is certainly one of the
- keys to FreeType's performance in certain areas (most importantly in
- glyph rendering/scanline-conversion).</p>
-
- <hr>
-
- <h2>
- 5. Summary
- </h2>
-
- <p>Finally, the following picture illustrates what has been said in this
- section, as well as the previous, by presenting the complete object
- graph of FreeType 2's base design:</p>
-
- <center>
- <img src="library-model.png"
- width=411 height=405
- alt="Complete library model">
- </center>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
- <a href="design-3.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-5.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/design/design-5.html
+++ /dev/null
@@ -1,458 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="design-4.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-6.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#ccccee"><td>
- <h1>
- IV. Module Classes
- </h1>
- </td></tr>
- </table>
-
- <p>We will now try to explain more precisely the <em>types</em> of modules
- that FreeType 2 is capable of managing. Note that each one of them
- is decribed with more details in the following chapters of this
- document.</p>
-
- <ul>
- <li>
- <p><em>Renderer</em> modules are used to manage scalable glyph images.
- This means <em>transforming</em> them, computing their <em>bounding
- box</em>, and <em>converting</em> them to either <em>monochrome</em>
- or <em>anti-aliased</em> bitmaps</em>.</p>
-
- <p>Note that FreeType 2 is capable of dealing with <em>any</em>
- kind of glyph images, as long as a renderer module is provided for it.
- The library comes by default with two renderers:</p>
-
- <p><table cellpadding=8>
- <tr valign=top>
- <td>
- <tt>raster</tt>
- </td>
- <td>
- <p>Supports the conversion of vectorial outlines (described by a
- <tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>smooth</tt>
- </td>
- <td>
- <p>Supports the conversion of the same outlines to high-quality
- <em>anti-aliased</em> pixmaps (using 256 levels of gray). Note
- that this renderer also supports direct span generation.</p>
- </td>
- </tr>
- </table></p>
-
- <li>
- <p><em>Font driver</em> modules are used to support one or more
- specific font format. By default, FreeType 2 comes with the
- following font drivers:</p>
-
- <p><table cellpadding=8>
- <tr valign=top>
- <td>
- <tt>truetype</tt>
- </td>
- <td>
- <p>supports TrueType font files</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>type1</tt>
- </td>
- <td>
- <p>supports Postscript Type 1 fonts, both in binary
- (<tt>.pfb</tt>) or ASCII (<tt>.pfa</tt>) formats, including
- Multiple Master fonts.</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>cid</tt>
- </td>
- <td>
- <p>supports Postscript CID-keyed fonts</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>cff</tt>
- </td>
- <td>
- <p>supports OpenType, CFF as well as CEF fonts (CEF is a
- derivative of CFF used by Adobe in its SVG viewer)</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>winfonts</tt>
- </td>
- <td>
- <p>supports Windows bitmap fonts (i.e. <tt>.fon</tt> and
- <tt>.fnt</tt>)</p>
- </td>
- </tr>
- </table></p>
-
- <p>Note that font drivers can support bitmapped or scalable glyph
- images. A given font driver that supports Bézier outlines
- through <tt>FT_Outline</tt> can also provide its own hinter, or rely
- on FreeType's <tt>autohinter</tt> module.</p>
- </li>
-
- <li>
- <p><em>Helper</em> modules are used to hold shared code that is often
- used by several font drivers, or even other modules. Here are the
- default helpers:</p>
-
- <p><table cellpadding=8>
- <tr valign=top>
- <td>
- <tt>sfnt</tt>
- </td>
- <td>
- used to support font formats based on the <tt>SFNT</tt> storage
- scheme: TrueType & OpenType fonts as well as other variants (like
- TrueType fonts that only contain embedded bitmaps)
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>psnames</tt>
- </td>
- <td>
- used to provide various useful functions related to glyph names
- ordering and Postscript encodings/charsets. For example, this
- module is capable of automatically synthetizing a Unicode charmap
- from a Type 1 glyph name dictionary.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>psaux</tt>
- </td>
- <td>
- used to provide various useful functions related to Type 1
- charstring decoding, as this "feature" is needed by the
- <tt>type1</tt>, <tt>cid</tt>, and <tt>cff</tt> drivers.
- </td>
- </tr>
- </table></p>
- </li>
-
- <li>
- <p>Finally, the <em>autohinter</em> module has a specific role in
- FreeType 2, as it can be used automatically during glyph loading
- to process individual glyph outlines when a font driver doesn't
- provide it's own hinting engine.</p>
-
- <p>This module's purpose and design is also heavily described on the
- FreeType web site.</p>
- </li>
- </ul>
-
- <p>We will now study how modules are described, then managed by the
- library.</p>
-
- <h3>
- 1. The <tt>FT_Module_Class</tt> structure
- </h3>
-
- <p>As described later in this document, library initialization is
- performed by calling the <tt>FT_Init_FreeType()</tt> function. The
- latter is in charge of creating a new "empty" <tt>FT_Library</tt>
- object, then register each "default" module by repeatedly calling the
- <tt>FT_Add_Module()</tt> function.</p>
-
- <p>Similarly, client applications can call <tt>FT_Add_Module()</tt> any
- time they wish in order to register a new module in the library. Let us
- take a look at this function's declaration:</p>
-
- <font color="blue"><pre>
- extern FT_Error FT_Add_Module(
- FT_Library library,
- const FT_Module_Class* clazz );</pre>
- </font>
-
- <p>As one can see, this function expects a handle to a library object,
- as well as a pointer to a <tt>FT_Module_Class</tt> structure. It
- returns an error code. In case of success, a new module object is
- created and added to the library. Note by the way that the module isn't
- returned directly by the call!</p>
-
- <p>Here the definition of <tt>FT_Module_Class</tt>, with some
- explanation. The following code is taken from
- <tt><freetype/ftmodule.h></tt>:</p>
-
- <font color="blue"><pre>
- typedef struct FT_Module_Class_
- {- FT_ULong module_flags;
- FT_Int module_size;
- const FT_String* module_name;
- FT_Fixed module_version;
- FT_Fixed module_requires;
-
- const void* module_interface;
-
- FT_Module_Constructor module_init;
- FT_Module_Destructor module_done;
- FT_Module_Requester get_interface;
-
- } FT_Module_Class;</pre>
- </font>
-
- <p>A description of its fields:</p>
-
- <p><table cellpadding=8>
- <tr valign=top>
- <td>
- <tt>module_flags</tt>
- </td>
- <td>
- <p>A set of bit flags used to describe the module's category. Valid
- values are:</p>
-
- <ul>
- <li>
- <tt>ft_module_font_driver</tt> if the module is a font driver
- </li>
- <li>
- <tt>ft_module_renderer</tt> if the module is a renderer
- </li>
- <li>
- <tt>ft_module_hinter</tt> if the module is an auto-hinter
- </li>
- <li>
- <tt>ft_module_driver_scalable</tt> if the module is a font
- driver supporting scalable glyph formats
- </li>
- <li>
- <tt>ft_module_driver_no_outlines</tt> if the module is a font
- driver supporting scalable glyph formats that <em>cannot</em> be
- described by an <tt>FT_Outline</tt> object
- </li>
- <li>
- <tt>ft_module_driver_has_hinter</tt> if the module is a font
- driver that provides its own hinting scheme/algorithm
- </li>
- </ul>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_size</tt>
- </td>
- <td>
- <p>An integer that gives the size in <em>bytes</em> of a given
- module object. This should <em>never</em> be less than
- <tt>sizeof(FT_ModuleRec)</tt>, but can be more if the module needs
- to sub-class the base <tt>FT_ModuleRec</tt> class.</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_name</tt>
- </td>
- <td>
- <p>The module's internal name, coded as a simple ASCII
- C string. There can't be two modules with the same name
- registered in a given <tt>FT_Library</tt> object. However,
- <tt>FT_Add_Module()</tt> uses the <tt>module_version</tt> field to
- detect module upgrades and perform them cleanly, even at
- run-time.</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_version</tt>
- </td>
- <td>
- <p>A 16.16 fixed float number giving the module's major and minor
- version numbers. It is used to determine whether a module needs to
- be upgraded when calling <tt>FT_Add_Module()</tt>.</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_requires</tt>
- </td>
- <td>
- <p>A 16.16 fixed float number giving the version of FreeType 2
- that is required to install this module. The default value is
- 0x20000 for FreeType version 2.0</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_requires</tt>
- </td>
- <td>
- <p>Most modules support one or more "interfaces", i.e. tables of
- function pointers. This field is used to point to the module's main
- interface, if there is one. It is a short-cut that prevents users
- of the module to call "get_interface()" each time they need to
- access one of the object's common entry points.</p>
-
- <p>Note that is is optional, and can be set to NULL. Other
- interfaces can also be accessed through the <tt>get_interface()</tt>
- field.</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_init</tt>
- </td>
- <td>
- <p>A pointer to a function used to initialize the fields of a fresh
- new <tt>FT_Module</tt> object. It is called <em>after</em> the
- module's base fields have been set by the library, and is generally
- used to initialize the fields of <tt>FT_ModuleRec</tt>
- subclasses.</p>
-
- <p>Most module classes set it to NULL to indicate that no extra
- initialization is necessary.</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>module_done</tt>
- </td>
- <td>
- <p>A pointer to a function used to finalize the fields of a given
- <tt>FT_Module</tt> object. Note that it is called <em>before</em>
- the library unsets the module's base fields, and is generally used
- to finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
-
- <p>Most module classes set it to NULL to indicate that no extra
- finalization is necessary</p>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>get_interface</tt>
- </td>
- <td>
- <p>A pointer to a function used to request the address of a given
- module interface. Set it to NULL if you don't need to support
- additional interfaces but the main one.</p>
- </td>
- </tr>
- </table></p>
-
-
- <h3>
- 2. The <tt>FT_Module</tt> type
- </h3>
-
- <p>The <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given
- module object/instance, whose base structure is given by the internal
- <tt>FT_ModuleRec</tt> type. We will intentionally <em>not</em> describe
- this structure here, as there is no point to look so far into the
- library's design.</p>
-
- <p>When <tt>FT_Add_Module</tt> is called, it first allocates a new
- module instance, using the <tt>module_size</tt> class field to determine
- its byte size. The function initializes the root <tt>FT_ModuleRec</tt>
- field, then calls the class-specific initializer <tt>module_init</tt>
- when this field is not set to NULL.</p>
-
- <p>Note that the library defines several sub-classes of
- <tt>FT_ModuleRec</tt>, which are, as you could have guessed:</p>
-
- <ul>
- <li><p><tt>FT_Renderer</tt> for renderer modules</p>
- <li><p><tt>FT_Driver</tt> for font driver modules</p>
- <li><p><tt>FT_AutoHinter</tt> for the auto-hinter</p>
- </ul>
-
- <p>Helper modules use the base <tt>FT_ModuleRec</tt> type. We will
- describe these classes in the next chapters.</p>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
- <a href="design-4.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="design-6.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/design/design-6.html
+++ /dev/null
@@ -1,94 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="design-5.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
-
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#ccccee"><td>
- <h1>
- TO BE CONTINUED...
- </h1>
- </td></tr>
- </table>
-
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
- <a href=design-5.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
-
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
binary files a/docs/design/detailed-design.png /dev/null differ
--- a/docs/design/index.html
+++ /dev/null
@@ -1,81 +1,0 @@
-<!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>The design of FreeType 2</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- The design of FreeType 2
-</h1>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-
-<center>
-<table width="70%">
-<tr><td>
-
- <p>This document describes the details of FreeType 2's internals.
- Read this carefully if you need to understand the innards of the library
- in order to hack or extend it.</p>
-
- <table width="100%">
- <tr valign=center
- bgcolor="#CCCCFF">
- <td align=center>
- <h2>
- Table of Contents
- </h2>
- </td>
- </tr>
- </table>
-
- <center>
- <table width="80%">
- <tr><td>
-
- <h2>
- <a href="design-1.html">Introduction</a>
- </h2>
-
- <h2>
- <a href="design-2.html">I. Components and APIs</a>
- </h2>
-
- <h2>
- <a href="design-3.html">II. Public Objects and Classes</a>
- </h2>
-
- <h2>
- <a href="design-4.html">III. Internal Objects and Classes</a>
- </h2>
-
- <h2>
- <a href="design-5.html">IV. Module Classes</a>
- </h2>
-
- </td></tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-</body>
-</html>
binary files a/docs/design/library-model.png /dev/null differ
--- a/docs/design/modules.html
+++ /dev/null
@@ -1,639 +1,0 @@
-<html>
-<head><title>FreeType 2 - Modules</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>
-
-<center><table width="500"><tr><td>
-
-<center><h1>FreeType 2 Modules</h1></center>
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Introduction</h1>
-</td></tr></table>
-
-<p>
-The purpose of this document is to present in great details the way
-FreeType 2 uses and manages modules. Among other things, it answers
-the following questions:</p>
-
-<ul>
- <li><p>
- what is a module, and what kind of modules are recognized
- by the library?
- </p></li>
-
- <li><p>
- how are modules registered and managed by the library?
- </p></li>
-
- <li><p>
- how to write a new module, especially new font drivers?
- </p></li>
-
- <li><p>
- how to select specific modules for a given build of the
- library ?
- </p></li>
-
- <li><p>
- how to compile modules as stand-alone DLLs / shared objects?
- </p></li>
-
-</ul>
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Overview</h1>
-</td></tr></table>
-
-
-<h3>1. Library design:</h3>
-
-<p>The design of the library is pretty basic:</p>
-<ul>
- <li><p>
- client applications typically call the FreeType 2 high-level
- API, whose functions are implemented in a single component
- called the <em>Base Layer</em>.
- </p></li>
-
- <li><p>
- depending on the context or the task, the base
- layer then calls one or more modules to perform the
- work. In most cases, the client application doesn't
- need to know what module was called.
- </p></li>
-
- <li><p>
- the base layer also contains a set of routines that are
- used for generic things like memory allocation, list
- processing, i/o stream parsing, fixed point computation,
- etc.. these functions can also be called by a module
- at any, and they form what is called the "low-level
- base API".
- </p></li>
-</ul>
-
-<p>This is illustrated by the following graphics:</p>
-
-<center><img src="basic-design.png" width="312" height="312"></center>
-
-<p>Note that, however, FT2 comes with a set of <em>optional</em>
-components that can be ommited from certain builds, and whose
-purpose vary between two situations:</p>
-
-<ul>
- <li><p>
- some are located on top of the high-level API and provide
- convenience functions that make certain things easier
- for typical applications. They typically do not call
- modules directly, though they can use the low level
- base API for certain tasks.</p>
-
- <p>As an example, see the the <tt>ftglyph</tt> component
- that is used to manipulate glyph images more conveniently
- than the default API.</p>
- </p></li>
-
- <li><p>
- some other components complement the base layer, by providing
- additional routines. Most of them allow client applications
- to access format-specific data.</p>
-
- <p>For example, the <tt>ftmm</tt> component provides high-level
- functions to specify Multiple Master coordinates for MM Type 1
- fonts.</p>
- </p></li>
-</ul>
-
-<p>This is illustrated by the following graphics:</p>
-
-<center><img src="detailed-design.png" width="365" height="392"></center>
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Module Classes</h1>
-</td></tr></table>
-
-<p>
-The library is capable of managing and using several kinds of
-modules:</p>
-
-<ul>
- <li><p>
- <b>renderer</b> modules are used to convert scalable glyph images
- to bitmaps. FreeType 2 comes by default with two of them:</p>
-
- <center><table cellpadding=5><tr valign=top><td>
- <p><b><tt>raster1</tt></b></p>
- </td><td>
- <p>supports the conversion of vectorial outlines (described by a
- <tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps.
- </td></tr><tr valign=top><td></p>
-
- <p><b><tt>smooth</tt></b></p>
- </td><td>
- <p>supports the conversion of the same outlines to high-quality
- <em>anti-aliased</em> pixmaps.</p>
- </td></tr></table></center>
-
-
- <p>The specification and interface of renderers is described in
- details within this document.</p>
-
- <p>Note that most font formats use <tt>FT_Outline</tt> objects
- to describe scalable glyph images. However, FT2 is flexible
- and allows specific modules to register and support other
- formats. As an example, it's (at least theorically :-) perfectly
- possible to write a renderer module that is capable of directly
- converting MetaFont glyph definitions to bitmaps or pixmaps !
- (of course, this assumes that you also write a MetaFont font
- driver to load the definitions :-).
- </p></li>
-
- <li><p>
- <b>font driver</b> modules are used to support one or more specific
- font format. By default, FT2 comes with the following modules:</p>
-
- <center><table cellpadding=5><tr valign=top><td>
- <p><tt><b>truetype</b></tt></p>
- </td><td>
- <p>supports TrueType font files</p>
- </td></tr><tr valign=top><td>
-
- <p><tt><b>type1</b></tt></p>
- </td><td>
- <p>supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII
- (.pfa) formats, including Multiple Master fonts.</p>
- </td></tr><tr valign=top><td>
-
- <p><tt><b>cid</b></tt></p>
- </td><td>
- <p>supports Postscript CID-keyed fonts</p>
- </td></tr><tr valign=top><td>
-
- <p><tt><b>cff</b></tt></p>
- </td><td>
- <p>supports OpenType, CFF as well as CEF fonts (CEF is a derivative
- of CFF used by Adobe in its SVG viewer).</p>
- </td></tr><tr valign=top><td>
-
- <p><tt><b>winfonts</b></tt></p>
- </td><td>
- <p>supports Windows bitmap fonts (i.e. ".FON" and ".FNT").</p>
- </td></tr>
-
- </td></tr></table></center>
-
- <p>Note that font drivers can support bitmapped or scalable glyph
- images. A given font driver that supports bezier outlines through
- the <tt>FT_Outline</tt> can also provide its own hinter, or rely
- on FreeType's <b>autohinter</b> module.
- </p></li>
-
- <li><p>
- <b>helper</b> modules are used to hold shared code that is
- often used by several font drivers, or even other modules.
- Here are a few examples of helper modules that come with
- FreeType 2:</p>
-
- <table cellpadding=5><tr valign=top><td>
- <b><tt>sfnt</tt></b>
- </td><td>
- used to support font formats based on the "<tt>SFNT</tt>"
- storage scheme. This means TrueType & OpenType fonts as
- well as other variants (like TrueType fonts that only
- contain embedded bitmaps).
- </td></tr><tr valign=top><td>
-
- <b><tt>psnames</tt></b>
- </td><td>
- used to provide various useful function related to glyph
- names ordering and Postscript encodings/charsets. For example,
- this module is capable of automatically synthetizing a Unicode
- charmap from a Type 1 glyph name dictionary.
- </td></tr></table></center>
- </p></li>
-
-
- <li><p>
- finally, the <b>autohinter</b> module has a specific role in
- FreeType 2, as it can be used automatically during glyph loading
- to process individual glyph outlines when a font driver doesn't
- provide it's own hinting engine.
- </p></li>
-</ul>
-
-<p>We will now study how modules are described, then managed by
- the library.</p>
-
-<h3>1. The <tt>FT_Module_Class</tt> structure:</h3>
-
-<p>As described later in this document, library initialisation is
- performed by calling the <tt>FT_Init_FreeType</tt> function. The
- latter is in charge of creating a new "empty" <tt>FT_Library</tt>
- object, then register each "default" module by repeatedly calling
- the <tt>FT_Add_Module</tt> function.</p>
-
-<p>Similarly, client applications can call <tt>FT_Add_Module</tt>
- any time they wish in order to register a new module in the library.
- Let's take a look at this function's declaration:</p>
-
-<pre><font color="blue">
- extern FT_Error FT_Add_Module( FT_Library library,
- const FT_Module_Class* clazz );
-</font></pre>
-
-<p>As one can see, this function expects a handle to a library object,
- as well as a pointer to a <tt>FT_Module_Class</tt> structure. It
- returns an error code. In case of success, a new module object is
- created and added to the library. Note by the way that the module
- isn't returned directly by the call !.</p>
-
-<p>Let's study the definition of <tt>FT_Module_Class</tt>, and explain it
- a bit. The following code is taken from
- <tt><freetype/ftmodule.h></tt>:</p>
-
-<pre><font color="blue">
- typedef struct FT_Module_Class_
- {- FT_ULong module_flags;
- FT_Int module_size;
- const FT_String* module_name;
- FT_Fixed module_version;
- FT_Fixed module_requires;
-
- const void* module_interface;
-
- FT_Module_Constructor module_init;
- FT_Module_Destructor module_done;
- FT_Module_Requester get_interface;
-
- } FT_Module_Class;
-</font></pre>
-
-<p>here's a description of its fields:</p>
-
-<center><table cellpadding=5><tr valign=top><td>
-<p><b>module_flags</b></p>
-</td><td>
-<p>this is a set of bit flags used to describe the module's
-category. Valid values are:</p>
- <ul>
- <li><p>
- <b>ft_module_font_driver</b> if the module is a font driver
- </p></li>
-
- <li><p>
- <b>ft_module_renderer</b> if the module is a renderer
- </p></li>
-
- <li><p>
- <b>ft_module_hinter</b> if the module is an auto-hinter
- </p></li>
-
- <li><p>
- <b>ft_module_driver_scalable</b> if the module is a font
- driver supporting scalable glyph formats.
- </p></li>
-
- <li><p>
- <b>ft_module_driver_no_outlines</b> if the module is a
- font driver supporting scalable glyph formats that <em>cannot</em>
- be described by a <tt>FT_Outline</tt> object
- </p></li>
-
- <li><p>
- <b>ft_module_driver_has_hinter</b> if the module is a font
- driver that provides its own hinting scheme/algorithm
- </p></li>
- </ul>
-</td></tr><tr valign=top><td>
-
-<p><b>module_size</b></p>
-</td><td>
-<p>an integer that gives the size in <em>bytes</em> of a given module
-object. This should <em>never</em> be less than
-<tt>sizeof(FT_ModuleRec)</tt>, but can be more when the module
-needs to sub-class the base <tt>FT_ModuleRec</tt> class.</p>
-</td></tr><tr valign=top><td>
-
-<p><b>module_name</b></p>
-</td><td>
-<p>this is the module's internal name, coded as a simple ASCII C
-string. There can't be two modules with the same name registered
-in a given <tt>FT_Library</tt> object. However, <tt>FT_Add_Module</tt>
-uses the <b>module_version</b> field to detect module upgrades
-and perform them cleanly, even at run-time.</p>
-</td></tr><tr valign=top><td>
-
-<p><b>module_version</b></p>
-</td><td>
-<p>a 16.16 fixed float number giving the module's major and minor
- version numbers. It is used to determine wether a module needs
- to be upgraded when calling <tt>FT_Add_Module</tt>.</p>
-</td></tr><tr valign=top><td>
-
-<p><b>module_requires</b></p>
-</td><td>
-<p>a 16.16 fixed float number giving the version of FreeType 2 that
- is required to install this module. By default, should be 0x20000
- for FreeType 2.0</p>
-</td></tr><tr valign=top><td>
-
-<p><b>module_requires</b></p>
-</td><td>
-<p>most modules support one or more "interfaces", i.e. tables of function
-pointers. This field is used to point to the module's main interface,
-where there is one. It's a short-cut that prevents users of the module
-to call "get_interface" each time they need to access one of the object's
-common entry points.</p>
-
-<p>Note that is is optional, and can be set to NULL. Other interfaces
-can also be accessed through the <b>get_interface</b> field.</p>
-</td></tr><tr valign=top><td>
-
-<p><b>module_init</b></p>
-</td><td>
-<p>this is a pointer to a function used to initialise the fields of
-a fresh new <tt>FT_Module</tt> object. It is called <em>after</em> the module's
-base fields have been set by the library, and is generally used to
-initialise the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
-
-<p>Most module classes set it to NULL to indicate that no extra
-initialisation is necessary</p>
-</td></tr><tr valign=top><td>
-
-<p><b>module_done</b></p>
-</td><td>
-<p>this is a pointer to a function used to finalise the fields of
-a given <tt>FT_Module</tt> object. Note that it is called <em>before</em> the
-library unsets the module's base fields, and is generally used to
-finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
-
-<p>Most module classes set it to NULL to indicate that no extra
-finalisation is necessary</p>
-</td></tr><tr valign=top><td>
-
-<p><b>get_interface</b></p>
-</td><td>
-<p>this is a pointer to a function used to request the address of
-a given module interface. Set it to NULL if you don't need to support
-additional interfaces but the main one.</p>
-</td></tr><tr valign=top><td>
-
-</td></tr></table></center>
-
-
-<h3>2. The <tt>FT_Module</tt> type:</h3>
-
-<p>the <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given
- module object / instance, whose base structure is given by the
- internal <tt>FT_ModuleRec</tt> type (we will not detail its
- structure here).</p>
-
-<p>When <tt>FT_Add_Module</tt> is called, it first allocate a new
- module instance, using the <tt><b>module_size</b></tt> class
- field to determine its byte size. The function initializes
- a the root <tt>FT_ModuleRec</tt> fields, then calls
- the class-specific initializer <tt><b>module_init</b></tt>
- when this field is not set to NULL.</p>
-
-
-
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Renderer Modules</h1>
-</td></tr></table>
-
-<p>As said previously, <b>renderers</b> are used to convert scalable
- glyph images to bitmaps or pixmaps. Each renderer module is defined
- through a <b>renderer class</b>, whose definition is found in the
- file <tt><freetype/ftrender.h></tt>. However, a few concepts
- need to be explained before having a detailed look at this structure.
- </p>
-
-<h3>1. Glyph formats:</h3>
-
-<p>Each glyph image that is loaded by FreeType (either through
- <tt>FT_Load_Glyph</tt> or <tt>FT_Load_Char</tt>), has a given
- <em>image format</em>, described by the field
- <tt>face->glyph->format</tt>. It is a 32-byte integer that
- can take any value. However, the file <tt><freetype/ftimage.h></tt>
- defines at least the following values:</p>
-
-<center><table cellpadding=5>
-<tr valign=top><td>
-<tt><b>ft_glyph_format_bitmap</b></tt>
-</td><td>
-this value is used to indicate that the glyph image is a bitmap or pixmap.
-Its content can then be accessed directly from
-<tt>face->glyph->bitmap</tt> after the glyph was loaded.
-</td></tr>
-
-<tr valign=top><td>
-<tt><b>ft_glyph_format_outline</b></tt>
-</td><td>
-this value is used to indicate that the glyph image is a scalable vectorial
-outline, that can be described by a <tt>FT_Outline</tt> object. Its content
-can be accessed directly from
-<tt>face->glyph->outline</tt> after the glyph was loaded.
-this is the format that is commonly returned by TrueType, Type1 and
-OpenType / CFF fonts.
-</td></tr>
-
-<tr valign=top><td>
-<tt><b>ft_glyph_format_plotter</b></tt>
-</td><td>
-this value is equivalent to <tt><b>ft_glyph_format_outline</b></tt> except
-that the outline stored corresponds to path strokes, instead of filled
-outlines. It can be returned from certain Type 1 fonts (notably the Hershey
-collection of free fonts).
-</td></tr>
-
-<tr valign=top><td>
-<tt><b>ft_glyph_format_composite</b></tt>
-</td><td>
-this value is used to indicate that the glyph image is really a "compound"
-of several other "sub-glyphs". This value is only returned when a glyph
-is loaded with the <tt><b>FT_LOAD_NO_RECURSE</b></tt> flag. The list of
-subglyphs that make up the composite can be accessed directly as
-<tt>face->glyph->subglyphs</tt> after the glyph was loaded.
-</td></tr>
-
-</table></center>
-
-<p>Note that this is only a list of pre-defined formats supported by
- FreeType. Nothing prevents an application to install a new font
- driver that creates other kinds of glyph images. For example, one
- could imagine a MetaFont font driver, that would be capable to
- parse font definition files and create in-memory "glyph programs",
- that could be returned in <tt>face->glyph->other</tt>.</p>
-
-<h3>2. The <tt>FT_Outline</tt> type:</h3>
-
-<p>This structure, which is also defined, and heavily commented, in
- the file <tt><freetype/ftimage.h></tt>, is used to hold
- a scalable glyph image that is made of one or more contours, each
- contour being described by line segments or bezier arcs (either
- quadratic or cubic). The outline itself is stored in a compact
- way that makes processing it easy.</p>
-
-<p>Points are placed in a 2D plane that uses the y-upwards convention,
- and their coordinates are stored in 1/64th of pixels (also known
- as the 26.6 fixed point format). Pixels correspond to single squares
- whose borders are on integer coordinates (i.e. mutiples of 64).
- In other words, pixel centers are located on half pixel coordinates.</p>
-
-<p>Outlines can be very easily transformed (translated, rotated, etc..)
- before being converted to bitmap, which allows for sophisticated
- use of text. FreeType 2 comes by default with two "outline renderer"
- modules:</p>
-
-<p><ul>
- <li><b>raster1</b>, used to convert them to monochrome bitmaps</li>
- <li><b>smooth</b>, used to convert them to high-quality anti-aliased
- pixmaps</li>
-</ul></p>
-
-<h3>3. Bitmaps and scan-conversion:</h3>
-
-<p>Bitmaps and pixmaps are described through a <tt>FT_Bitmap</tt>
- structure, which is defined and heavily commented in
- <tt><freetype/ftimage.h></tt>
-
-
-<pre><font color="blue">
- typedef struct FT_Renderer_Class_
- {- FT_Module_Class root;
-
- FT_Glyph_Format glyph_format;
-
- FTRenderer_render render_glyph;
- FTRenderer_transform transform_glyph;
- FTRenderer_getCBox get_glyph_cbox;
- FTRenderer_setMode set_mode;
-
- FT_Raster_Funcs* raster_class;
-
- } FT_Renderer_Class;
-</font></pre>
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Font Driver Modules</h1>
-</td></tr></table>
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Library Initialisation & Dynamic Builds</h1>
-</td></tr></table>
-
-<p>By default, all components of FreeType 2 are compiled independently,
- then grouped into a single static library file that can be installed
- or used directly to compile client applications</p>
-
-<p>Such applications must normally call the <tt>FT_Init_FreeType</tt>
- function before using the library. This function is in charge of
- two things:</p>
-
-<ul>
- <li><p>
- First, it creates a <tt>FT_Library</tt> object (by calling
- the public function <tt>FT_New_Library</tt>). This new
- object is "empty" and has no module registered in it.
- </p></li>
-
- <li><p>
- Then, it registers all "default modules" by repeatedly calling
- <tt>FT_Add_Module</tt>.
- </p></li>
-</ul>
-
-<p>It is important to notice that the default implementation of
- <tt>FT_Init_FreeType</tt>, which is located in the source
- file <tt>"src/base/ftinit.c"</tt> always uses a <em>static</em>
- list of modules that is generated at compile time from the
- configuration file <tt><freetype/config/ftmodule.h></tt>.
-</p>
-
-<p>There are cases where this may be inadequate. For example, one
- might want to compile modules as independent DLLs in a specific
- location (like <tt>"/usr/lib/freetype/module/"</tt>), and have
- the library initialisation function load the modules dynamically
- by parsing the directory's content</p>
-
-<p>This is possible, and we're going to explain how to do it.</p>
-
-
-<h4>a. Building the library as a DLL (i.e. "shared object" on Unix)</h4>
-
-<p>But first of all, let's explain how to build FreeType 2 as a single
- DLL or shared object, i.e. one that includes the base layer, all
- default modules and optional components into a single file.</p>
-
-<p>When building dynamic libraries, certain compilers require specific
- directives to <em>declare</em> exported DLL entry points. For example, the
- "<tt>__cdecl</tt>" directive is required by Win32 compilers, as it forces
- the use of the "C" parameter passing convention (instead of "smarter"
- schemes, which usually use registers and the stack to pass parameters).</p>
-
-<p>To make matter worse, some of these compilers require the directive
- before the function's return type, while some others want it between
- the return type and the function's identifier.</p>
-
-<p>To allow such compilations, the <tt>FT_EXPORT_DEF()</tt> macro is
- used in all public header files in order to declare each high-level
- API function of FreeType 2, as in the following example, taken from
- <tt><freetype/freetype.h></tt>:</p>
-
-<pre><font color="blue">
- FT_EXPORT_DEF(FT_Error) FT_Init_FreeType( void );
-</font></pre>
-
-<p>the definition of <tt>FT_EXPORT_DEF(x)</tt> defaults to <tt>"extern x"</tt>,
- except when a specific definition is given in the library's system-specific
- configuration file <tt><freetype/config/ftconfig.h></tt>. This
- allows project builders to specify the exact compilation directive
- they need.</p>
-
-<p>Similarly, the <tt>FT_EXPORT_FUNC(x)</tt> macro is defined and used to
- <em>define</em> exported functions within the FreeType 2 source code.
- However, it is only used at compilation time.</p>
-
-
-<p>Note that on Unix, there is no need for specific exportation directives.
- However, the code must be compiled in a special way, named Position
- Independent Code ("PIC"), which is normally selected through specific- compiler flags (like "-PIC" with gcc).</p>
-
-
-<h4>b. Building modules as DLLs</h4>
-
-<p>In order to build modules as dynamic libraries, we first need to compile
- the base layer (and optional components) as a single DLL. This is very
- similar to the case we just described, except that we also need to
- export all functions that are part of the "low level base API",
- as these will get called by the modules in various cases.</p>
-
-<p>Similarly to the high-level API, all functions of the low-level base
- API are declared in the internal header files of FreeType 2 with the
- <tt>BASE_DEF(x)</tt> macro. The latter is similar to
- <tt>FT_EXPORT_DEF</tt> and defaults to <tt>"extern x"</tt> unless
- you specify a specific definition in
- <tt><freetype/config/ftconfig.h></tt>.</p>
-<p>
-
-<hr>
-
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>Conclusion</h1>
-</td></tr></table>
-
-</td></tr></table></center>
-</body>
-</html>
binary files a/docs/design/simple-model.png /dev/null differ
--- a/docs/freetype2.html
+++ /dev/null
@@ -1,352 +1,0 @@
-<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:[email protected]">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>
--- a/docs/ft2faq.html
+++ /dev/null
@@ -1,729 +1,0 @@
-<!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 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 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
- to FreeType 1.x?</a>
- </li>
- <li>
- <a href="#general-edit">Can I use FreeType 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 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>
- </p></ul>
- </li>
- <li>
- <a href="#autohint">The FreeType 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 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 2 renderer?</a>
- </li>
- <li>
- <a href="#other-opentype">When will FreeType 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 :-) 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
- developing 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>
-
- <hr>
- <a name="general-long">
- <h3>
- I.2 Why did it take so long to release FreeType 2?
- </h3>
-
- <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
- 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 :-)</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 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 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 2 a Unix-only project?
- </h3>
-
- <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 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 :-)</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>
- 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.
- </li>
- <li>
- 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.
- </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 2 backwards compatible with FreeType 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 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>
-
- <hr>
- <a name="general-edit">
- <h3>
- I.6 Can I use FreeType 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 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 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 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 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 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 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 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 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 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 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 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 2 auto-hinter
- </h2>
- </td></tr>
- <tr><td>
-
- <a name="autohint-license">
- <h3>
- III.1 Under which license is the FreeType 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 :-)</p>
-
- <p>To give a few details, the auto-hinter is used to perform
- grid-fitting on scalable font formats that use Bé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 1/Type 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><freetype/ftimage.h></tt> contains the definition of
- the <tt>FT_Raster_Params</tt> type used with direct rendering.</p>
- </li>
- <li>
- <p><tt><freetype/ftoutln.h></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, &outline, &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 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 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 2 anti-aliasing renderer is indeed <em>faster</em>
- than the monochrome renderer for small character sizes (typically
- <20 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 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 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 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 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>
binary files a/docs/glyphs/Image1.png /dev/null differ
binary files a/docs/glyphs/Image2.png /dev/null differ
binary files a/docs/glyphs/Image3.png /dev/null differ
binary files a/docs/glyphs/Image4.png /dev/null differ
binary files a/docs/glyphs/bbox1.png /dev/null differ
binary files a/docs/glyphs/bbox2.png /dev/null differ
binary files a/docs/glyphs/body_comparison.png /dev/null differ
binary files a/docs/glyphs/bravo_kerned.png /dev/null differ
binary files a/docs/glyphs/bravo_unkerned.png /dev/null differ
binary files a/docs/glyphs/clipping.png /dev/null differ
binary files a/docs/glyphs/down_flow.png /dev/null differ
--- a/docs/glyphs/glyphs-1.html
+++ /dev/null
@@ -1,199 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
-
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-2.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- I. Basic typographic concepts
- </h2>
- </td></tr>
- </table>
-
- <a name="section-1">
- <h3>
- 1. Font files, format and information
- </h3>
-
- <p>A font is a collection of various character images that can be used
- to display or print text. The images in a single font share some common
- properties, including look, style, serifs, etc. Typographically
- speaking, one has to distinguish between a <em>font family</em> and its
- multiple <em>font faces</em>, which usually differ in style though come
- from the same template.</p>
-
- For example, "Palatino Regular" and "Palatino Italic" are two distinct
- <em>faces</em> from the same famous <em>family</em>, called "Palatino"
- itself.</p>
-
- <p>The single term <em>font</em> is nearly always used in ambiguous ways
- to refer to either a given family or given face, depending on the
- context. For example, most users of word-processors use "font" to
- describe a font family (e.g. "Courier", "Palatino", etc.); however most
- of these families are implemented through several data files depending
- on the file format: For TrueType, this is usually one per face (i.e.
- <tt>arial.ttf</tt> for "Arial Regular", <tt>ariali.ttf</tt> for "Arial
- Italic", etc.). The file is also called a "font" but really contains a
- font face.</p>
-
- <p>A <em>digital font</em> is thus a data file that may contain <em>one
- or more font faces</em>. For each of these, it contains character
- images, character metrics, as well as other kind of information
- important to the layout of text and the processing of specific character
- encodings. In some awkward formats, like Adobe's Type 1, a single
- font face is described through several files (i.e. one contains the
- character images, another one the character metrics). We will ignore
- this implementation issue in most parts of this document and consider
- digital fonts as single files, though FreeType 2.0 is able to
- support multiple-files fonts correctly.</p>
-
- <p>As a convenience, a font file containing more than one face is called
- a <em>font collection</em>. This case is rather rare but can be seen in
- many Asian fonts, which contain images for two or more representation
- forms of a given scripts (usually for horizontal and vertical
- layout.</p>
-
-
- <a name="section-2">
- <h3>
- 2. Character images and mappings
- </h3>
-
- <p>The character images are called <em>glyphs</em>. A single character
- can have several distinct images, i.e. several glyphs, depending on
- script, usage or context. Several characters can also take a single
- glyph (good examples are Roman ligatures like "fi" and "fl" which can be
- represented by a single glyph). The relationships between characters
- and glyphs can be very complex, but won't be discussed in this document.
- Moreover, some formats use more or less awkward schemes to store and
- access glyphs. For the sake of clarity, we only retain the following
- notions when working with FreeType:</p>
-
- <ul>
- <li>
- <p>A font file contains a set of glyphs; each one can be stored as a
- bitmap, a vector representation or any other scheme (most scalable
- formats use a combination of mathematical representation and control
- data/programs). These glyphs can be stored in any order in the font
- file, and is typically accessed through a simple glyph index.</p>
- </li>
- <li>
- <p>The font file contains one or more tables, called a <em>character
- map</em> (or charmap in short), which is used to convert character
- codes for a given encoding (e.g. ASCII, Unicode, DBCS, Big5, etc..)
- into glyph indices relative to the font file. A single font face
- may contain several charmaps. For example, most TrueType fonts
- contain an Apple-specific charmap as well as a Unicode charmap,
- which makes them usable on both Mac and Windows platforms.</p>
- </li>
- </ul>
-
-
- <a name="section-3">
- <h3>
- 3. Character and font metrics
- </h3>
-
- <p>Each glyph image is associated with various metrics which are used to
- describe how it must be placed and managed when rendering text. These
- are described in more details in section III; they relate to glyph
- placement, cursor advances as well as text layout. They are extremely
- important to compute the flow of text when rendering a string of
- text.</p>
-
- <p>Each scalable format also contains some global metrics, expressed in
- notional units, to describe some properties of all glyphs in the same
- face. Examples for global metrics are the maximum glyph bounding box,
- the ascender, descender and text height for the font.</p>
-
- <p>Though these metrics also exist for non-scalable formats, they only
- apply for a set of given character dimensions and resolutions, and are
- usually expressed in pixels.</p>
-
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC" valign=center>
- <td align=center
- width="30%">
-
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-2.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/glyphs/glyphs-2.html
+++ /dev/null
@@ -1,397 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-1.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-3.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- II. Glyph outlines
- </h2>
- </td></tr>
- </table>
-
- <p>This section describes the way scalable representations of glyph
- images, called outlines, are used by FreeType as well as client
- applications.</p>
-
- <a name="section-1">
- <h3>
- 1. Pixels, points and device resolutions
- </h3>
-
- <p>Though it is a very common assumption when dealing with computer
- graphics programs, the physical dimensions of a given pixel (be it for
- screens or printers) are not squared. Often, the output device, be it a
- screen or printer, exhibits varying resolutions in both horizontal and
- vertical direction, and this must be taken care of when rendering
- text.</p>
-
- <p>It is thus common to define a device's characteristics through two
- numbers expressed in <em>dpi</em> (dots per inch). For example, a
- printer with a resolution of 300x600 dpi has 300 pixels per
- inch in the horizontal direction, and 600 in the vertical one. The
- resolution of a typical computer monitor varies with its size
- (15" and 17" monitors don't have the same pixel sizes at
- 640x480), and of course the graphics mode resolution.</p>
-
- <p>As a consequence, the size of text is usually given in
- <em>points</em>, rather than device-specific pixels. Points are a
- simple <em>physical</em> unit, where 1 point = 1/72th of
- an inch, in digital typography. As an example, most Roman books are
- printed with a body text whose size is somewhere between 10 and
- 14 points.</p>
-
- <p>It is thus possible to compute the size of text in pixels from the
- size in points with the following formula:</p>
-
- <center>
- <tt>pixel_size = point_size * resolution / 72</tt>
- </center>
-
- <p>The resolution is expressed in <em>dpi</em>. Since horizontal and
- vertical resolutions may differ, a single point size usually defines a
- different text width and height in pixels.</p>
-
- <p><em>Unlike what is often thought, the "size of text in pixels" is not
- directly related to the real dimensions of characters when they are
- displayed or printed. The relationship between these two concepts is a
- bit more complex and relate to some design choices made by the font
- designer. This is described in more detail in the next sub-section (see
- the explanations on the EM square).</em></p>
-
-
- <a name="section-2">
- <h3>
- 2. Vectorial representation
- </h3>
-
- <p>The source format of outlines is a collection of closed paths called
- <em>contours</em>. Each contour delimits an outer or inner
- <em>region</em> of the glyph, and can be made of either <em>line
- segments</em> or <em>Bézier arcs</em>.</p>
-
- <p>The arcs are defined through <em>control points</em>, and can be
- either second-order (these are <em>conic</em> Béziers) or
- third-order (<em>cubic</em> Béziers) polynomials, depending on
- the font format. Note that conic Béziers are usually called
- <em>quadratic</em> Béziers in the literature. Hence, each point
- of the outline has an associated flag indicating its type (normal or
- control point). And scaling the points will scale the whole
- outline.</p>
-
- <p>Each glyph's original outline points are located on a grid of
- indivisible units. The points are usually stored in a font file as
- 16-bit integer grid coordinates, with the grid origin's being at (0,0);
- they thus range from -16384 to 16383. (Even though point
- coordinates can be floats in other formats such as Type 1, we will
- restrict our analysis to integer values for simplicity).</p>
-
- <p><em>The grid is always oriented like the traditional mathematical
- two-dimensional plane, i.e., the <i>X</i> axis from the left to the
- right, and the <i>Y</i> axis from bottom to top.</em></p>
-
- <p>In creating the glyph outlines, a type designer uses an imaginary
- square called the <em>EM square</em>. Typically, the EM square can be
- thought of as a tablet on which the characters are drawn. The square's
- size, i.e., the number of grid units on its sides, is very important for
- two reasons:</p>
-
- <ul>
- <li>
- <p>It is the reference used to scale the outlines to a given text
- dimension. For example, a size of 12pt at 300x300 dpi
- corresponds to 12*300/72 = 50 pixels. This is the
- size the EM square would appear on the output device if it was
- rendered directly. In other words, scaling from grid units to
- pixels uses the formula:</p>
-
- <p><center>
- <tt>pixel_size = point_size * resolution / 72</tt><br>
- <tt>pixel_coord = grid_coord * pixel_size / EM_size</tt>
- </center></p>
- </li>
- <li>
- <p>The greater the EM size is, the larger resolution the designer
- can use when digitizing outlines. For example, in the extreme
- example of an EM size of 4 units, there are only 25 point
- positions available within the EM square which is clearly not
- enough. Typical TrueType fonts use an EM size of 2048 units;
- Type 1 PostScript fonts have a fixed EM size of 1000 grid
- units but point coordinates can be expressed as floating values.</p>
- </li>
- </ul>
-
- <p>Note that glyphs can freely extend beyond the EM square if the font
- designer wants so. The EM is used as a convenience, and is a valuable
- convenience from traditional typography.</p>
-
- <p>Grid units are very often called <em>font units</em> or <em>EM
- units</em>.</p>
-
- <p><em>As said before, <tt>pixel_size</tt> computed in the above formula
- does not relate directly to the size of characters on the screen. It
- simply is the size of the EM square if it was to be displayed. Each
- font designer is free to place its glyphs as it pleases him within the
- square. This explains why the letters of the following text have not
- the same height, even though they are displayed at the same point size
- with distinct fonts:</em>
-
- <p><center>
- <img src="body_comparison.png"
- height=40 width=580
- alt="Comparison of font heights">
- </center></p>
-
- <p>As one can see, the glyphs of the Courier family are smaller than
- those of Times New Roman, which themselves are slightly smaller than
- those of Arial, even though everything is displayed or printed at a size
- of 16 points. This only reflects design choices.</p>
-
-
- <a name="section-3">
- <h3>
- 3. Hinting and Bitmap rendering
- </h3>
-
- <p>The outline as stored in a font file is called the "master" outline,
- as its points coordinates are expressed in font units. Before it can be
- converted into a bitmap, it must be scaled to a given size/resolution.
- This is done through a very simple transformation, but always creates
- undesirable artifacts, e.g. stems of different widths or heights in
- letters like "E" or "H".</p>
-
- <p>As a consequence, proper glyph rendering needs the scaled points to
- be aligned along the target device pixel grid, through an operation
- called <em>grid-fitting</em> (often called<em>hinting</em>). One of its
- main purposes is to ensure that important widths and heights are
- respected throughout the whole font (for example, it is very often
- desirable that the "I" and the "T" have their central vertical line of
- the same pixel width), as well as to manage features like stems and
- overshoots, which can cause problems at small pixel sizes.</p>
-
- <p>There are several ways to perform grid-fitting properly; most
- scalable formats associate some control data or programs with each glyph
- outline. Here is an overview:</p>
-
- <ul>
- <li>
- <p><em>explicit grid-fitting</em></p>
-
- <p>The TrueType format defines a stack-based virtual machine, for
- which programs can be written with the help of more than
- 200 opcodes (most of these relating to geometrical operations).
- Each glyph is thus made of both an outline and a control program to
- perform the actual grid-fitting in the way defined by the font
- designer.</p>
- </li>
- <li>
- <p><em>implicit grid-fitting (also called hinting)</em></p>
-
- <p>The Type 1 format takes a much simpler approach: Each glyph
- is made of an outline as well as several pieces called
- <em>hints</em> which are used to describe some important features of
- the glyph, like the presence of stems, some width regularities, and
- the like. There aren't a lot of hint types, and it is up to the
- final renderer to interpret the hints in order to produce a fitted
- outline.</p>
- </li>
- <li>
- <p><em>automatic grid-fitting</em></p>
-
- <p>Some formats simply include no control information with each
- glyph outline, apart from metrics like the advance width and height.
- It is then up to the renderer to "guess" the more interesting
- features of the outline in order to perform some decent
- grid-fitting.</p>
- </li>
- </ul>
-
- <p>The following table summarises the pros and cons of each scheme.</p>
-
- <center>
- <table width="90%"
- bgcolor="#CCCCCC"
- cellpadding=5>
- <tr bgcolor="#999999">
- <td>
- <center>
- <b>grid-fitting scheme</b>
- </center>
- </td>
- <td>
- <center>
- <b>advantages</b>
- </center>
- </td>
- <td>
- <center>
- <b>disadvantages</b>
- </center>
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <center>
- <b>explicit</b>
- </center>
- </td>
-
- <td valign=top>
- <p><b>Quality.</b> Excellent results at small sizes are possible.
- This is very important for screen display.</p>
-
- <p><b>Consistency.</b> All renderers produce the same glyph
- bitmaps.</p>
- </td>
-
- <td valign=top>
- <p><b>Speed.</b> Intepreting bytecode can be slow if the glyph
- programs are complex.</p>
-
- <p><b>Size.</b> Glyph programs can be long.</p>
-
- <p><b>Technical difficulty.</b>
- It is extremely difficult to write good hinting
- programs. Very few tools available.</p>
- </td>
- </tr>
- <tr>
- <td valign=top>
- <center>
- <b>implicit</b>
- </center>
- </td>
-
- <td valign=top>
- <p><b>Size.</b> Hints are usually much smaller than explicit glyph
- programs.</p>
-
- <p><b>Speed.</b>
- Grid-fitting is usually a fast process.</p>
- </td>
-
- <td valign=top>
- <p><b>Quality.</b> Often questionable at small sizes. Better with
- anti-aliasing though.</p>
-
- <p><b>Inconsistency.</b> Results can vary between different
- renderers, or even distinct versions of the same engine.</p>
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <center>
- <b>automatic</b>
- </center>
- </td>
-
- <td valign=top>
- <p><b>Size.</b> No need for control information, resulting in
- smaller font files.</p>
-
- <p><b>Speed.</b> Depends on the grid-fitting algorithm. Usually
- faster than explicit grid-fitting.</p>
- </td>
-
- <td valign=top>
- <p><b>Quality.</b> Often questionable at small sizes. Better with
- anti-aliasing though.</p>
-
- <p><b>Speed.</b> Depends on the grid-fitting algorithm.</p>
-
- <p><b>Inconsistency.</b> Results can vary between different
- renderers, or even distinct versions of the same engine.</p>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-1.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-3.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/glyphs/glyphs-3.html
+++ /dev/null
@@ -1,430 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-2.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-4.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- III. Glyph metrics
- </h2>
- </td></tr>
- </table>
-
- <a name="section-1">
- <h3>
- 1. Baseline, pens and layouts
- </h3>
-
- <p>The baseline is an imaginary line that is used to "guide" glyphs when
- rendering text. It can be horizontal (e.g. Roman, Cyrillic, Arabic,
- etc.) or vertical (e.g. Chinese, Japanese, Korean, etc). Moreover, to
- render text, a virtual point, located on the baseline, called the <em>pen
- position</em> or <em>origin</em>, is used to locate glyphs.</p>
-
- <p>Each layout uses a different convention for glyph placement:</p>
-
- <ul>
- <li>
- <p>With horizontal layout, glyphs simply "rest" on the baseline.
- Text is rendered by incrementing the pen position, either to the
- right or to the left.</p>
-
- <p>The distance between two successive pen positions is
- glyph-specific and is called the <em>advance width</em>. Note that
- its value is <em>always</em> positive, even for right-to-left
- oriented alphabets, like Arabic. This introduces some differences
- in the way text is rendered.</p>
-
- <p><em>The pen position is always placed on the baseline.</em></p>
-
- <p><center>
- <img src="Image1.png"
- height=179 width=458
- alt="horizontal layout">
- </center></p>
- </li>
- <li>
- <p>With a vertical layout, glyphs are centered around the
- baseline:</p>
-
- <p><center>
- <img src="Image2.png"
- height=275 width=162
- alt="vertical layout">
- </center></p>
- </li>
- </ul>
-
-
- <a name="section-2">
- <h3>
- 2. Typographic metrics and bounding boxes
- </h3>
-
- <p>A various number of face metrics are defined for all glyphs in a
- given font.</p>
-
- <ul>
- <li>
- <p><em>Ascent</em></p>
-
- <p>The distance from the baseline to the highest/upper grid
- coordinate used to place an outline point. It is a positive value,
- due to the grid's orientation with the <i>Y</i> axis
- upwards.</p>
- </li>
-
- <li>
- <p><em>Descent</em></p>
-
- <p>The distance from the baseline to the lowest grid coordinate used
- to place an outline point. This is a negative value, due to the
- grid's orientation.</p>
- </li>
-
- <li>
- <p><em>Linegap</em></p>
-
- <p>The distance that must be placed between two lines of text. The
- baseline-to-baseline distance should be computed as:
-
- <center><p>
- <tt>ascent - descent + linegap</tt>
- </p></center>
-
- <p>if you use the typographic values.</p>
- </li>
- </ul>
-
- <p>Other, simpler metrics are:</p>
-
- <ul>
- <li>
- <p><em>The glyph's bounding box</em>, also called <em>bbox</em></p>
-
- <p>This is an imaginary box that encloses all glyphs from the font,
- usually as tightly as possible. It is represented by four fields,
- namely <tt>xMin</tt>, <tt>yMin</tt>, <tt>xMax</tt>, and
- <tt>yMax</tt>, that can be computed for any outline. Their values
- can be in font units (if measured in the original outline) or in
- fractional/integer pixel units (when measured on scaled
- outlines).</p>
-
- <p>Note that if it wasn't for grid-fitting, you wouldn't need to
- know a box's complete values, but only its dimensions to know how
- big is a glyph outline/bitmap. However, correct rendering of hinted
- glyphs needs the preservation of important grid alignment on each
- glyph translation/placement on the baseline.</p>
- </li>
-
- <li>
- <p><em>Internal leading</em></p>
-
- <p>This concept comes directly from the world of traditional
- typography. It represents the amount of space within the
- <em>leading</em> which is reserved for glyph features that lay
- outside of the EM square (like accentuation). It usually can be
- computed as:</p>
-
- <center><p>
- <tt>internal leading = ascent - descent - EM_size</tt>
- </p></center>
- </li>
-
- <li>
- <p><em>External leading</em></p>
-
- <p>This is another name for the line gap.</p>
- </li>
- </ul>
-
-
- <a name="section-3">
- <h3>
- 3. Bearings and Advances
- </h3>
-
- Each glyph has also distances called <em>bearings</em> and
- <em>advances</em>. Their definition is constant, but their values
- depend on the layout, as the same glyph can be used to render text
- either horizontally or vertically:
-
- <ul>
- <li>
- <p><em>Left side bearing</em> or <em>bearingX</em></p>
-
- <p>The horizontal distance from the current pen position to the
- glyph's left bbox edge. It is positive for horizontal layouts, and
- in most cases negative for vertical ones.</p>
- </li>
-
- <li>
- <p><em>Top side bearing</em> or <em>bearingY</em></p>
-
- <p>The vertical distance from the baseline to the top of the glyph's
- bbox. It is usually positive for horizontal layouts, and negative
- for vertical ones.</p>
- </li>
-
- <li>
- <p><em>Advance width</em> or <em>advanceX</em></p>
-
- <p>The horizontal distance the pen position must be incremented (for
- left-to-right writing) or decremented (for right-to-left writing) by
- after each glyph is rendered when processing text. It is always
- positive for horizontal layouts, and null for vertical ones.</p>
- </li>
-
- <li>
- <p><em>Advance height</em> <em>advanceY</em></p>
-
- <p>The vertical distance the pen position must be decremented by
- after each glyph is rendered. It is always null for horizontal
- layouts, and positive for vertical layouts.</p>
- </li>
-
- <li>
- <p><em>Glyph width</em></p>
-
- <p>The glyph's horizontal extent. For unscaled font coordinates, it
- is <tt>bbox.xMax-bbox.xMin</tt>. For scaled glyphs, its computation
- requests specific care, described in the grid-fitting chapter
- below.</p>
- </li>
-
- <li>
- <p><em>Glyph height</em>
-
- <p>The glyph's vertical extent. For unscaled font coordinates, it is
- <tt>bbox.yMax-bbox.yMin</tt>. For scaled glyphs, its computation
- requests specific care, described in the grid-fitting chapter
- below.</p>
- </li>
-
- <li>
- <p><em>Right side bearing</em></p>
-
- <p>Only used for horizontal layouts to describe the distance from
- the bbox's right edge to the advance width. It is in most cases a
- non-negative number:</p>
-
- <p><center>
- <tt>advance_width - left_side_bearing - (xMax-xMin)</tt>
- </center></p>
- </li>
- </ul>
-
- <p>Here is a picture giving all the details for horizontal metrics:
-
- <center><p>
- <img src="Image3.png"
- height=253 width=388
- alt="horizontal glyph metrics">
- </p></center>
-
- <p>And here is another one for the vertical metrics:</p>
-
- <center><p>
- <img src="Image4.png"
- height=278 width=294
- alt="vertical glyph metrics">
- </p></center>
-
-
- <a name="section-4">
- <h3>
- 4. The effects of grid-fitting
- </h3>
-
- <p>Because hinting aligns the glyph's control points to the pixel grid,
- this process slightly modifies the dimensions of character images in
- ways that differ from simple scaling.</p>
-
- <p>For example, the image of the lowercase "m" letter sometimes fits a
- square in the master grid. However, to make it readable at small pixel
- sizes, hinting tends to enlarge its scaled outline in order to keep its
- three legs distinctly visible, resulting in a larger character
- bitmap.</p>
-
- <p>The glyph metrics are also influenced by the grid-fitting process:
-
- <ul>
- <li>
- The image's width and height are altered. Even if this is only by
- one pixel, it can make a big difference at small pixel sizes.
- </li>
- <li>
- The image's bounding box is modified, thus modifying the bearings.
- </li>
- <li>
- The advances must be updated. For example, the advance width must
- be incremented if the hinted bitmap is larger than the scaled one,
- to reflect the augmented glyph width.
- </li>
- </ul>
-
- <p>This has some implications:</p>
-
- <ul>
- <li>
- Because of hinting, simply scaling the font ascent or descent might
- not give correct results. A possible solution is to keep the
- ceiling of the scaled ascent, and floor of the scaled descent.
- </li>
-
- <li>
- There is no easy way to get the hinted glyph and advance widths of a
- range of glyphs, as hinting works differently on each outline. The
- only solution is to hint each glyph separately and record the
- returned values. Some formats, like TrueType, even include a table
- of pre-computed values for a small set of common character pixel
- sizes.
- </li>
- <li>
- Hinting depends on the final character width and height in pixels,
- which means that it is highly resolution-dependent. This property
- makes correct WYSIWYG layouts difficult to implement.
- </li>
- </ul>
-
-
- <em>
- <p>Performing 2D transformations on glyph outlines is very easy with
- FreeType. However, when using translation on a hinted outlines, one
- should aways take care of <b>exclusively using integer pixel
- distances</b> (which means that the parameters to the
- <tt>FT_Translate_Outline()</tt> API should all be multiples
- of 64, as the point coordinates are in 26.6 fixed float
- format).</p>
-
- <p>Otherwise, the translation will simply <em>ruin the hinter's
- work</em>, resulting in a very low quality bitmaps!</p>
- </em>
-
-
- <a name="section-5">
- <h3>
- 5. Text widths and bounding box
- </h3>
-
- <p>As seen before, the "origin" of a given glyph corresponds to the
- position of the pen on the baseline. It is not necessarily located on
- one of the glyph's bounding box corners, unlike many typical bitmapped
- font formats. In some cases, the origin can be out of the bounding box,
- in others, it can be within it, depending on the shape of the given
- glyph.</p>
-
- <p>Likewise, the glyph's "advance width" is the increment to apply to
- the pen position during layout, and is not related to the glyph's
- "width", which really is the glyph's bounding width.
-
- <p>The same conventions apply to strings of text. This means that:
-
- <ul>
- <li>
- The bounding box of a given string of text doesn't necessarily
- contain the text cursor, nor is the latter located on one of its
- corners.
- </li>
-
- <li>
- The string's advance width isn't related to its bounding box
- dimensions. Especially if it contains beginning and terminal spaces
- or tabs.
- </li>
- <li>
- Finally, additional processing like kerning creates strings of text
- whose dimensions are not directly related to the simple
- juxtaposition of individual glyph metrics. For example, the advance
- width of "VA" isn't the sum of the advances of "V" and "A" taken
- separately.
- </li>
- </ul>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-2.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-4.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/glyphs/glyphs-4.html
+++ /dev/null
@@ -1,231 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-3.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-4.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- IV. Kerning
- </h2>
- </td></tr>
- </table>
-
- <p>The term <em>kerning</em> refers to specific information used to
- adjust the relative positions of coincident glyphs in a string of text.
- This section describes several types of kerning information, as well as
- the way to process them when performing text layout.</p>
-
-
- <a name="section-1">
- <h3>
- 1. Kerning pairs
- </h3>
-
- <p>Kerning consists of modifying the spacing between two successive
- glyphs according to their outlines. For example, a "T" and a "y" can be
- easily moved closer, as the top of the "y" fits nicely under the upper
- right bar of the "T".</p>
-
- <p>When laying out text with only their standard widths, some
- consecutive glyphs seem a bit too close or too distant. For example,
- the space between the "A" and the "V" in the following word seems a
- little wider than needed.</p>
-
- <center><p>
- <img src="bravo_unkerned.png"
- height=37 width=116
- alt="the word 'bravo' unkerned">
- </p></center>
-
- <p>Compare this to the same word, where the distance between these two
- letters has been slightly reduced:</p>
-
- <center><p>
- <img src="bravo_kerned.png"
- height=37 width=107
- alt="the word 'bravo' with kerning">
- </p></center>
-
- <p>As you can see, this adjustment can make a great difference. Some
- font faces thus include a table containing kerning distances for a set
- of given glyph pairs for text layout.</p>
-
- <ul>
- <li>
- <p>The pairs are ordered, i.e., the space for pair (A,V) isn't
- necessarily the space for pair (V,A). They also index glyphs, and
- not characters.</p>
- </li>
- <li>
- <p>Kerning distances can be expressed in horizontal or vertical
- directions, depending on layout and/or script. For example, some
- horizontal layouts like Arabic can make use of vertical kerning
- adjustments between successive glyphs. A vertical script can have
- vertical kerning distances.</p>
- </li>
- <li>
- <p>Kerning distances are expressed in grid units. They are usually
- oriented in the <i>X</i> axis, which means that a negative
- value indicates that two glyphs must be set closer in a horizontal
- layout.</p>
- </li>
- </ul>
-
-
- <a name="section-2">
- <h3>
- 2. Applying kerning
- </h3>
-
- <p>Applying kerning when rendering text is a rather easy process. It
- merely consists in adding the scaled kern distance to the pen position
- before writing each next glyph. However, the typographically correct
- renderer must take a few more details in consideration.</p>
-
- <p>The "sliding dot" problem is a good example: Many font faces include
- a kerning distance between capital letters like "T" or "F" and a
- following dot ("."), in order to slide the latter glyph just right to- their main leg:</p>
-
- <center><p>
- <img src="twlewis1.png"
- height=38 width=314
- alt="example for sliding dots">
- </p></center>
-
- <p>This sometimes requires additional adjustments between the dot and
- the letter following it, depending on the shapes of the enclosing
- letters. When applying "standard" kerning adjustments, the previous
- sentence would become:</p>
-
- <center><p>
- <img src="twlewis2.png"
- height=36 width=115
- alt="example for too much kerning">
- </p></center>
-
- <p>This is clearly too contracted. The solution here, as exhibited in
- the first example, is to only slide the dots when possible. Of course,
- this requires a certain knowledge of the text's meaning. The above
- adjustments would not necessarily be welcome if we were rendering the
- final dot of a given paragraph.</p.
-
- <p>This is only one example, and there are many others showing that a
- real typographer is needed to layout text properly. If not available,
- some kind of user interaction or tagging of the text could be used to
- specify some adjustments, but in all cases, this requires some support
- in applications and text libraries.</p>
-
- <p>For more mundane and common uses, however, we can have a very simple
- algorithm, which avoids the sliding dot problem, and others, though not
- producing optimal results. It can be seen as</p>
-
- <ol>
- <li>
- Place the first glyph on the baseline.
- </li>
- <li>
- Save the location of the pen position/origin in <tt>pen1</tt>.
- </li>
- <li>
- Adjust the pen position with the kerning distance between the first
- and second glyph.
- </li>
- <li>
- Place the second glyph and compute the next pen position/origin in
- <tt>pen2</tt>.
- </li>
- <li>
- Use <tt>pen1</tt> as the next pen position if it is beyond
- <tt>pen2</tt>, use <tt>pen2</tt> otherwise.
- </li>
- </ol>
-
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-3.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-5.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/glyphs/glyphs-5.html
+++ /dev/null
@@ -1,484 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-4.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-6.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- V. Text processing
- </h2>
- </td></tr>
- </table>
-
- <p>This section demonstrates how to use the concepts previously defined
- to render text, whatever the layout you use.</p>
-
-
- <a name="section-1">
- <h3>
- 1. Writing simple text strings
- </h3>
-
- <p>In this first example, we will generate a simple string of Roman
- text, i.e. with a horizontal left-to-right layout. Using exclusively
- pixel metrics, the process looks like:
-
- <tt>
- <ol>
- <li>
- Convert the character string into a series of glyph
- indices.
- </li>
- <li>
- Place the pen to the cursor position.
- </li>
- <li>
- Get or load the glyph image.
- </li>
- <li>
- Translate the glyph so that its 'origin' matches the pen position.
- </li>
- <li>
- Render the glyph to the target device.
- </li>
- <li>
- Increment the pen position by the glyph's advance width in pixels.
- </li>
- <li>
- Start over at step 3 for each of the remaining glyphs.
- </li>
- <li>
- When all glyphs are done, set the text cursor to the new pen
- position.
- </li>
- </ol>
- </tt>
-
- <p>Note that kerning isn't part of this algorithm.</p>
-
-
- <a name="section-2">
- <h3>
- 2. Sub-pixel positioning
- </h3>
-
- <p>It is somewhat useful to use sub-pixel positioning when rendering
- text. This is crucial, for example, to provide semi-WYSIWYG text
- layouts. Text rendering is very similar to the algorithm described in
- subsection 1, with the following few differences:</p>
-
- <ul>
- <li>
- The pen position is expressed in fractional pixels.
- </li>
- <li>
- Because translating a hinted outline by a non-integer distance will
- ruin its grid-fitting, the position of the glyph origin must be
- rounded before rendering the character image.
- </li>
- <li>
- The advance width is expressed in fractional pixels, and isn't
- necessarily an integer.
- </li>
- </ol>
-
- <p>Here an improved version of the algorithm:</p>
-
- <tt>
- <ol>
- <li>
- Convert the character string into a series of glyph
- indices.
- </li>
- <li>
- Place the pen to the cursor position. This can be a non-integer
- point.
- </li>
- <li>
- Get or load the glyph image.
- </li>
- <li>
- Translate the glyph so that its "origin" matches the rounded pen
- position.
- </li>
- <li>
- Render the glyph to the target device.
- </li>
- <li>
- Increment the pen position by the glyph's advance width in
- fractional pixels.
- </li>
- <li>
- Start over at step 3 for each of the remaining glyphs.
- </li>
- <li>
- When all glyphs are done, set the text cursor to the new pen
- position.
- </li>
- </ol>
- </tt>
-
- <p>Note that with fractional pixel positioning, the space between two
- given letters isn't fixed, but determined by the accumulation of
- previous rounding errors in glyph positioning.</p>
-
-
- <a name="section-3">
- <h3>
- 3. Simple kerning
- </h3>
-
- <p>Adding kerning to the basic text rendering algorithm is easy: When a
- kerning pair is found, simply add the scaled kerning distance to the pen
- position before step 4. Of course, the distance should be rounded
- in the case of algorithm 1, though it doesn't need to for
- algorithm 2. This gives us:</p>
-
- <p>Algorithm 1 with kerning:</p>
-
- <tt>
- <ol>
- <li>
- Convert the character string into a series of glyph
- indices.
- </li>
- <li>
- Place the pen to the cursor position.
- </li>
- <li>
- Get or load the glyph image.
- </li>
- <li>
- Add the rounded scaled kerning distance, if any, to the pen
- position.
- </li>
- <li>
- Translate the glyph so that its "origin" matches the pen position.
- </li>
- <li>
- Render the glyph to the target device.
- </li>
- <li>
- Increment the pen position by the glyph's advance width in pixels.
- </li>
- <li>
- Start over at step 3 for each of the remaining glyphs.
- </li>
- </ol>
- </tt>
-
- <p>Algorithm 2 with kerning:</p>
-
- <tt>
- <ol>
- <li>
- Convert the character string into a series of glyph
- indices.
- </li>
- <li>
- Place the pen to the cursor position.
- </li>
- <li>
- Get or load the glyph image.
- </li>
- <li>
- Add the scaled unrounded kerning distance, if any, to the pen
- position.
- </li>
- <li>
- Translate the glyph so that its "origin" matches the rounded pen
- position.
- </li>
- <li>
- Render the glyph to the target device.
- </li>
- <li>
- Increment the pen position by the glyph's advance width in
- fractional pixels.
- </li>
- <li>
- Start over at step 3 for each of the remaining glyphs.
- </li>
- </ol>
- </tt>
-
- Of course, the algorithm described in section IV can also be
- applied to prevent the sliding dot problem if one wants to.
-
-
- <a name="section-4">
- <h3>
- 4. Right-to-left layout
- </h3>
-
- <p>The process of laying out Arabic or Hebrew text is extremely similar.
- The only difference is that the pen position must be decremented before
- the glyph rendering (remember: the advance width is always positive,
- even for Arabic glyphs).</p>
-
- <p>Right-to-left algorithm 1:</p>
-
- <tt>
- <ol>
- <li>
- Convert the character string into a series of glyph
- indices.
- </li>
- <li>
- Place the pen to the cursor position.
- </li>
- <li>
- Get or load the glyph image.
- </li>
- <li>
- Decrement the pen position by the glyph's advance width in pixels.
- </li>
- <li>
- Translate the glyph so that its "origin" matches the pen position.
- </li>
- <li>
- Render the glyph to the target device.
- </li>
- <li>
- Start over at step 3 for each of the remaining glyphs.
- </li>
- </ol>
- </tt>
-
- <p>The changes to algorithm 2, as well as the inclusion of kerning
- are left as an exercise to the reader.</p>
-
-
- <a name="section-5">
- <h3>
- 5. Vertical layouts
- </h3>
-
- <p>Laying out vertical text uses exactly the same processes, with the
- following significant differences:</p>
-
- <ul>
- <li>
- <p>The baseline is vertical, and the vertical metrics must be used
- instead of the horizontal one.</p>
- </li>
- <li>
- <p>The left bearing is usually negative, but this doesn't change the
- fact that the glyph origin must be located on the baseline.</p>
- </li>
- <li>
- The advance height is always positive, so the pen position must be
- decremented if one wants to write top to bottom (assuming the
- <i>Y</i> axis is oriented upwards).
- </li>
- </ul>
-
- <p>Here the algorithm:</p>
-
- <tt>
- <ol>
- <li>
- Convert the character string into a series of glyph
- indices.
- </li>
- <li>
- Place the pen to the cursor position.
- </li>
- <li>
- Get or load the glyph image.
- </li>
- <li>
- Translate the glyph so that its "origin" matches the pen position.
- </li>
- <li>
- Render the glyph to the target device.
- </li>
- <li>
- Decrement the vertical pen position by the glyph's advance height
- in pixels.
- </li>
- <li>
- Start over at step 3 for each of the remaining glyphs.
- </li>
- <li>
- When all glyphs are done, set the text cursor to the new pen
- position.
- </li>
- </ol>
- </tt>
-
-
- <a name="section-6">
- <h3>
- 6. WYSIWYG text layouts
- </h3>
-
- <p>As you probably know, the acronym WYSIWYG stands for "What You See Is
- What You Get". Basically, this means that the output of a document on
- the screen should match "perfectly" its printed version. A
- <em>true</em> WYSIWYG system requires two things:</p>
-
- <ul>
- <li>
- <p><em>device-independent text layout</em></p>
-
- <p>This means that the document's formatting is the same on the
- screen than on any printed output, including line breaks,
- justification, ligatures, fonts, position of inline images, etc.</p>
- </li>
- <li>
- <p><em>matching display and print character sizes</em></p>
-
- <p>The displayed size of a given character should match its
- dimensions when printed. For example, a text string which is
- exactly 1 inch tall when printed should also appear 1 inch
- tall on the screen (when using a scale of 100%).</p>
- </li>
- </ul>
-
- <p>It is clear that matching sizes cannot be possible if the computer
- has no knowledge of the physical resolutions of the display device(s) it
- is using. And of course, this is the most common case! That is not too
- unfortunate, however, because most users really don't care about this
- feature. Legibility is much more important.</p>
-
- <p>When the Mac appeared, Apple decided to choose a resolution of
- 72 dpi to describe the Macintosh screen to the font sub-system
- (whatever the monitor used). This choice was most probably driven by
- the fact that, at this resolution, 1 point equals exactly
- 1 pixel. However, it neglected one crucial fact: As most users
- tend to choose a document character size between 10 and 14 points,
- the resultant displayed text was rather small and not too legible
- without scaling. Microsoft engineers took notice of this problem and
- chose a resolution of 96 dpi on Windows, which resulted in slightly
- larger, and more legible, displayed characters (for the same printed
- text size).</p>
-
- <p>These distinct resolutions explain some differences when displaying
- text at the same character size on a Mac and a Windows machine.
- Moreover, it is not unusual to find some TrueType fonts with enhanced
- hinting (technical note: through delta-hinting) for the sizes of 10, 12,
- 14 and 16 points at 96 dpi.</p>
-
- <p>The term <em>device-independent text</em> is, unfortunately, often
- abused. For example, many word processors, including MS Word, do
- not really use device-independent glyph positioning algorithms when
- laying out text. Rather, they use the target printer's resolution to
- compute <em>hinted</em> glyph metrics for the layout. Though it
- guarantees that the printed version is always the "nicest" it can be,
- especially for very low resolution printers (like dot-matrix), it has a
- very sad effect: Changing the printer can have dramatic effects on the
- <em>whole</em> document layout, especially if it makes strong use of
- justification, uses few page breaks, etc.</p>
-
- <p>Because glyph metrics vary slightly when the resolution changes (due
- to hinting), line breaks can change enormously, when these differences
- accumulate over long runs of text. Try for example printing a very long
- document (with no page breaks) on a 300 dpi ink-jet printer, then
- the same one on a 3000 dpi laser printer: You will be extremely
- lucky if your final page count didn't change between the prints! Of
- course, we can still call this WYSIWYG, as long as the printer
- resolution is fixed.</p>
-
- <p>Some applications, like Adobe Acrobat, which targeted
- device-independent placement from the start, do not suffer from this
- problem. There are two ways to achieve this: either use the scaled and
- unhinted glyph metrics when laying out text both in the rendering and
- printing processes, or simply use whatever metrics you want and store
- them with the text in order to get sure they are printed the same on all
- devices (the latter being probably the best solution, as it also enables
- font substitution without breaking text layouts).</p>
-
- <p>Just like matching sizes, device-independent placement isn't
- necessarily a feature that most users want. However, it is pretty clear
- that for any kind of professional document processing work, it
- <em>is</em> a requirement.</p>
-
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-4.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-6.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/glyphs/glyphs-6.html
+++ /dev/null
@@ -1,432 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-5.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-7.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- VI. FreeType outlines
- </h2>
- </td></tr>
- </table>
-
- <p>The purpose of this section is to present the way FreeType manages
- vectorial outlines, as well as the most common operations that can be
- applied on them.</p>
-
- <a name="section-1">
- <h3>
- 1. FreeType outline description and structure
- </h3>
-
- <h4>
- a. Outline curve decomposition
- </h4>
-
- <p>An outline is described as a series of closed contours in the 2D
- plane. Each contour is made of a series of line segments and
- Bézier arcs. Depending on the file format, these can be
- second-order or third-order polynomials. The former are also called
- quadratic or conic arcs, and they are used in the TrueType format.
- The latter are called cubic arcs and are mostly used in the
- Type 1 format.</p>
-
- <p>Each arc is described through a series of start, end, and control
- points. Each point of the outline has a specific tag which indicates
- whether it is used to describe a line segment or an arc. The tags can
- take the following values:</p>
-
- <center>
- <table cellspacing=5
- cellpadding=5
- width="80%">
- <tr VALIGN=TOP>
- <td valign=top>
- <tt>FT_Curve_Tag_On</tt>
- </td>
- <td valign=top>
- <p>Used when the point is "on" the curve. This corresponds to
- start and end points of segments and arcs. The other tags specify
- what is called an "off" point, i.e. a point which isn't located on
- the contour itself, but serves as a control point for a
- Bézier arc.</p>
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>FT_Curve_Tag_Conic</tt>
- </td>
- <td valign=top>
- <p>Used for an "off" point used to control a conic Bézier
- arc.</p>
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>FT_Curve_Tag_Cubic</tt>
- </td>
- <td valign=top>
- <p>Used for an "off" point used to control a cubic Bézier
- arc.</p>
- </td>
- </tr>
- </table>
- </center>
-
- <p>The following rules are applied to decompose the contour's points
- into segments and arcs:</p>
-
- <ul>
- <li>
- Two successive "on" points indicate a line segment joining them.
- </li>
- <li>
- One conic "off" point amidst two "on" points indicates a conic
- Bézier arc, the "off" point being the control point, and
- the "on" ones the start and end points.
- </li>
- <li>
- Two successive cubic "off" points amidst two "on" points indicate
- a cubic Bézier arc. There must be exactly two cubic
- control points and two "on" points for each cubic arc (using a
- single cubic "off" point between two "on" points is forbidden, for
- example).
- </li>
- <li>
- Finally, two successive conic "off" points forces the rasterizer
- to create (during the scan-line conversion process exclusively) a
- virtual "on" point amidst them, at their exact middle. This
- greatly facilitates the definition of successive conic
- Bézier arcs. Moreover, it is the way outlines are
- described in the TrueType specification.
- </li>
- </ul>
-
- <p>Note that it is possible to mix conic and cubic arcs in a single
- contour, even though no current font driver produces such
- outlines.</p>
-
- <center>
- <table>
- <tr>
- <td>
- <img src="points_segment.png"
- height=166 width=221
- alt="segment example">
- </td>
- <td>
- <img src="points_conic.png"
- height=183 width=236
- alt="conic arc example">
- </td>
- </tr>
- <tr>
- <td>
- <img src="points_cubic.png"
- height=162 width=214
- alt="cubic arc example">
- </td>
- <td>
- <img src="points_conic2.png"
- height=204 width=225
- alt="cubic arc with virtual 'on' point">
- </td>
- </tr>
- </table>
- </center>
-
-
- <h4>
- b. Outline descriptor
- </h4>
-
- <p>A FreeType outline is described through a simple structure:</p>
-
- <center>
- <table cellspacing=3
- cellpadding=3>
- <caption>
- <b><tt>FT_Outline</tt></b>
- </caption>
-
- <tr>
- <td>
- <tt>n_points</tt>
- </td>
- <td>
- the number of points in the outline
- </td>
- </tr>
- <tr>
- <td>
- <tt>n_contours</tt>
- </td>
- <td>
- the number of contours in the outline
- </td>
- </tr>
- <tr>
- <td>
- <tt>points</tt>
- </td>
- <td>
- array of point coordinates
- </td>
- </tr>
- <tr>
- <td>
- <tt>contours</tt>
- </td>
- <td>
- array of contour end indices
- </td>
- </tr>
- <tr>
- <td>
- <tt>tags</tt>
- </td>
- <td>
- array of point flags
- </td>
- </tr>
- </table>
- </center>
-
- <p>Here, <tt>points</tt> is a pointer to an array of
- <tt>FT_Vector</tt> records, used to store the vectorial coordinates of
- each outline point. These are expressed in 1/64th of a pixel, which
- is also known as the <em>26.6 fixed float format</em>.</p>
-
- <p><tt>contours</tt> is an array of point indices used to delimit
- contours in the outline. For example, the first contour always starts
- at point 0, and ends at point <tt>contours[0]</tt>. The second
- contour starts at point <tt>contours[0]+1</tt> and ends at
- <tt>contours[1]</tt>, etc.</p>
-
- <p>Note that each contour is closed, and that <tt>n_points</tt> should
- be equal to <tt>contours[n_contours-1]+1</tt> for a valid outline.</p>
-
- <p>Finally, <tt>tags</tt> is an array of bytes, used to store each
- outline point's tag.</p>
-
-
- <a name="section-2">
- <h3>
- 2. Bounding and control box computations
- </h3>
-
- <p>A <em>bounding box</em> (also called <em>bbox</em>) is simply a
- rectangle that completely encloses the shape of a given outline. The
- interesting case is the smallest bounding box possible, and in the
- following we subsume this under the term "bounding box". Because of the
- way arcs are defined, Bézier control points are not necessarily
- contained within an outline's (smallest) bounding box.</p>
-
- <p>This situation happens when one Bézier arc is, for example,
- the upper edge of an outline and an "off" point happens to be above the
- bbox. However, it is very rare in the case of character outlines
- because most font designers and creation tools always place "on" points
- at the extrema of each curved edges, as it makes hinting much
- easier.</p>
-
- <p>We thus define the <em>control box</em> (also called <em>cbox</em>)
- as the smallest possible rectangle that encloses all points of a given
- outline (including its "off" points). Clearly, it always includes the
- bbox, and equates it in most cases.</p>
-
- <p>Unlike the bbox, the cbox is much faster to compute.</p>
-
- <center>
- <table>
- <tr>
- <td>
- <img src="bbox1.png"
- height=264 width=228
- alt="a glyph with different bbox and cbox">
- </td>
- <td>
- <img src="bbox2.png"
- height=229 width=217
- alt="a glyph with identical bbox and cbox">
- </td>
- </tr>
- </table>
- </center>
-
- <p>Control and bounding boxes can be computed automatically through the
- functions <tt>FT_Get_Outline_CBox()</tt> and
- <tt>FT_Get_Outline_BBox()</tt>. The former function is always very
- fast, while the latter <em>may</em> be slow in the case of "outside"
- control points (as it needs to find the extreme of conic and cubic arcs
- for "perfect" computations). If this isn't the case, it is as fast as
- computing the control box.
-
- <p>Note also that even though most glyph outlines have equal cbox and
- bbox to ease hinting, this is not necessary the case anymore when a
- transformation like rotation is applied to them.</p>
-
-
- <a name="section-3">
- <h3>
- 3. Coordinates, scaling and grid-fitting
- </h3>
-
- <p>An outline point's vectorial coordinates are expressed in the
- 26.6 format, i.e. in 1/64th of a pixel, hence the coordinates
- (1.0,-2.5) are stored as the integer pair (x:64,y:-192).</p>
-
- <p>After a master glyph outline is scaled from the EM grid to the
- current character dimensions, the hinter or grid-fitter is in charge of
- aligning important outline points (mainly edge delimiters) to the pixel
- grid. Even though this process is much too complex to be described in a
- few lines, its purpose is mainly to round point positions, while trying
- to preserve important properties like widths, stems, etc.</p>
-
- <p>The following operations can be used to round vectorial distances in
- the 26.6 format to the grid:</p>
-
- <pre>
- round( x ) == ( x + 32 ) & -64
- floor( x ) == x & -64
- ceiling( x ) == ( x + 63 ) & -64</pre>
-
- <p>Once a glyph outline is grid-fitted or transformed, it often is
- interesting to compute the glyph image's pixel dimensions before
- rendering it. To do so, one has to consider the following:</p>
-
- <p>The scan-line converter draws all the pixels whose <em>centers</em>
- fall inside the glyph shape. It can also detect <em>drop-outs</em>,
- i.e. discontinuities coming from extremely thin shape fragments, in
- order to draw the "missing" pixels. These new pixels are always located
- at a distance less than half of a pixel but it is not easy to predict
- where they will appear before rendering.</p>
-
- <p>This leads to the following computations:</p>
-
- <ul>
- <li>
- <p>compute the bbox</p>
- </li>
- <li>
- <p>grid-fit the bounding box with the following:</p>
-
- <pre>
- xmin = floor( bbox.xMin )
- xmax = ceiling( bbox.xMax )
- ymin = floor( bbox.yMin )
- ymax = ceiling( bbox.yMax )</pre>
- </li>
- <li>
- return pixel dimensions, i.e.
-
- <pre>
- width = (xmax - xmin)/64</pre>
-
- and
-
- <pre>
- height = (ymax - ymin)/64</pre>
- </li>
- </ul>
-
- <p>By grid-fitting the bounding box, it is guaranteed that all the pixel
- centers that are to be drawn, <em>including those coming from drop-out
- control</em>, will be <em>within</em> the adjusted box. Then the box's
- dimensions in pixels can be computed.</p>
-
- <p>Note also that, when translating a grid-fitted outline, one should
- <em>always use integer distances</em> to move an outline in the 2D
- plane. Otherwise, glyph edges won't be aligned on the pixel grid
- anymore, and the hinter's work will be lost, producing <em>very low
- quality </em>bitmaps and pixmaps.</p>
-
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-5.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
- <a href="glyphs-7.html">Next</a>
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/glyphs/glyphs-7.html
+++ /dev/null
@@ -1,356 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-<center>
-<table width="65%">
-<tr><td>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-6.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
-
- </td>
- </tr>
- </table>
- </center>
-
- <p><hr></p>
-
- <table width="100%">
- <tr bgcolor="#CCCCFF"
- valign=center><td>
- <h2>
- VII. FreeType bitmaps
- </h2>
- </td></tr>
- </table>
-
- <p>The purpose of this section is to present the way FreeType manages
- bitmaps and pixmaps, and how they relate to the concepts previously
- defined. The relationships between vectorial and pixel coordinates is
- explained.</p>
-
-
- <a name="section-1">
- <h3>
- 1. Vectorial versus pixel coordinates
- </h3>
-
- <p>This sub-section explains the differences between vectorial and pixel
- coordinates. To make things clear, brackets will be used to describe
- pixel coordinates, e.g. [3,5], while parentheses will be used for
- vectorial ones, e.g. (-2,3.5).</p>
-
- <p>In the pixel case, as we use the <em>Y upwards</em> convention;
- the coordinate [0,0] always refers to the <em>lower left pixel</em> of a
- bitmap, while coordinate [width-1, rows-1] to its <em>upper right
- pixel</em>.</p>
-
- <p>In the vectorial case, point coordinates are expressed in floating
- units, like (1.25, -2.3). Such a position doesn't refer to a given
- pixel, but simply to an immaterial point in the 2D plane.</p>
-
- <p>The pixels themselves are indeed <em>square boxes</em> of the 2D
- plane, whose centers lie in half pixel coordinates. For example, the
- lower left pixel of a bitmap is delimited by the square (0,0)-(1,1), its
- center being at location (0.5,0.5).</p>
-
- <p>This introduces some differences when computing distances. For
- example, the <em>length</em> in pixels of the line [0,0]-[10,0] is 11.
- However, the vectorial distance between (0,0)-(10,0) covers exactly
- 10 pixel centers, hence its length is 10.</p>
-
- <center>
- <img src="grid_1.png"
- height=390 width=402
- alt="bitmap and vector grid">
- </center>
-
-
- <a name="section-2">
- <h3>
- 2. FreeType bitmap and pixmap descriptor
- </h3>
-
- <p>A bitmap or pixmap is described through a single structure, called
- <tt>FT_Bitmap</tt>, defined in the file
- <tt><freetype/ftimage.h></tt>. It is a simple descriptor whose
- fields are:</p>
-
- <center>
- <table cellspacing=3
- cellpadding=5
- width="80%">
- <caption>
- <b><tt>FT_Bitmap</tt></b>
- </caption>
-
- <tr>
- <td valign=top>
- <tt>rows</tt>
- </td>
- <td valign=top>
- the number of rows, i.e. lines, in the bitmap
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>width</tt>
- </td>
- <td valign=top>
- the number of horizontal pixels in the bitmap
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>pitch</tt>
- </td>
- <td valign=top>
- its absolute value is the number of bytes per bitmap line; it can
- be either positive or negative depending on the bitmap's vertical
- orientation
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>buffer</tt>
- </td>
- <td valign=top>
- a typeless pointer to the bitmap pixel bufer
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>pixel_mode</tt>
- </td>
- <td valign=top>
- an enumeration used to describe the pixel format of the bitmap;
- examples are <tt>ft_pixel_mode_mono</tt> for 1-bit monochrome
- bitmaps and <tt>ft_pixel_mode_grays</tt> for 8-bit anti-aliased
- "gray" values
- </td>
- </tr>
-
- <tr>
- <td valign=top>
- <tt>num_grays</tt>
- </td>
- <td valign=top>
- this is only used for "gray" pixel modes; it gives the number of
- gray levels used to describe the anti-aliased gray levels --
- FreeType 2 defaults to 256 grays.
- </td>
- </tr>
- </table>
- </center>
-
-
- <p>Note that the sign of the <tt>pitch</tt> fields determines whether
- the rows in the pixel buffer are stored in ascending or descending
- order.</p>
-
- <p>Remember that FreeType uses the <em>Y upwards</em> convention in
- the 2D plane, which means that a coordinate of (0,0) always refer to the
- <em>lower-left corner</em> of a bitmap.</p>
-
- <p>If the pitch is positive, the rows are stored in decreasing vertical
- position; the first bytes of the pixel buffer are part of the
- <em>upper</em> bitmap row.</p>
-
- <p>On the opposite, if the pitch is negative, the first bytes of the
- pixel buffer are part of the <em>lower</em> bitmap row.</p>
-
- <p>In all cases, one can see the pitch as the byte increment needed to
- skip to the <em>next lower scanline</em> in a given bitmap buffer.</p>
-
- <center>
- <table>
- <tr>
- <td>
- <img src="up_flow.png"
- height=261 width=275
- alt="negative 'pitch'">
- </td>
- <td>
- <img src="down_flow.png"
- height=263 width=273
- alt="positive 'pitch'">
- </td>
- </tr>
- </table>
- </center>
-
- <p>The "positive pitch" convention is very often used, though
- some systems might need the other.</p>
-
-
- <a name="section-3">
- <h3>
- 3. Converting outlines into bitmaps and pixmaps
- </h3>
-
- <p>Generating a bitmap or pixmap image from a vectorial image is easy
- with FreeType. However, one must understand a few points regarding the
- positioning of the outline in the 2D plane before converting it to a
- bitmap:</p>
-
- <ul>
- <li>
- <p>The glyph loader and hinter always places the outline in the 2D
- plane so that (0,0) matches its character origin. This means that
- the glyph's outline, and corresponding bounding box, can be placed
- anywhere in the 2D plane (see the graphics in section III).</p>
- </li>
- <li>
- <p>The target bitmap's area is mapped to the 2D plane, with its
- lower left corner at (0,0). This means that a bitmap or pixmap of
- dimensions [<tt>w,h</tt>] will be mapped to a 2D rectangle window
- delimited by (0,0)-(<tt>w,h</tt>).</p>
- </li>
- <li>
- <p>When scan-converting the outline, everything that falls within
- the bitmap window is rendered, the rest is ignored.</p>
- </li>
-
- <p>A common mistake made by many developers when they begin using
- FreeType is believing that a loaded outline can be directly rendered
- in a bitmap of adequate dimensions. The following images illustrate
- why this is a problem.</p>
-
- <ul>
- <li>
- The first image shows a loaded outline in the 2D plane.
- </li>
- <li>
- The second one shows the target window for a bitmap of arbitrary
- dimensions [w,h].
- </li>
- <li>
- The third one shows the juxtaposition of the outline and window in
- the 2D plane.
- </li>
- <li>
- The last image shows what will really be rendered in the bitmap.
- </li>
- </ul>
-
- <center>
- <img src="clipping.png"
- height=151 width=539
- alt="clipping algorithm">
- </center>
- </ul>
-
- <p>Indeed, in nearly all cases, the loaded or transformed outline must
- be translated before it is rendered into a target bitmap, in order to
- adjust its position relative to the target window.</p>
-
- <p>For example, the correct way of creating a <em>standalone</em> glyph
- bitmap is as follows</p>
-
- <ul>
- <li>
- <p>Compute the size of the glyph bitmap. It can be computed
- directly from the glyph metrics, or by computing its bounding box
- (this is useful when a transformation has been applied to the
- outline after the load, as the glyph metrics are not valid
- anymore).</p>
- </li>
- <li>
- <p>Create the bitmap with the computed dimensions. Don't forget to
- fill the pixel buffer with the background color.</p>
- </li>
- <li>
- <p>Translate the outline so that its lower left corner matches
- (0,0). Don't forget that in order to preserve hinting, one should
- use integer, i.e. rounded distances (of course, this isn't required
- if preserving hinting information doesn't matter, like with rotated
- text). Usually, this means translating with a vector
- <tt>(-ROUND(xMin), -ROUND(yMin))</tt>.</p>
- </li>
- <li>
- <p>Call the rendering function (it can be
- <tt>FT_Outline_Render()</tt> for example).</p>
- </li>
- </ul>
-
- <p>In the case where one wants to write glyph images directly into a
- large bitmap, the outlines must be translated so that their vectorial
- position correspond to the current text cursor/character origin.</p>
-
- <p><hr></p>
-
- <center>
- <table width="100%"
- border=0
- cellpadding=5>
- <tr bgcolor="#CCFFCC"
- valign=center>
- <td align=center
- width="30%">
- <a href="glyphs-6.html">Previous</a>
- </td>
- <td align=center
- width="30%">
- <a href="index.html">Contents</a>
- </td>
- <td align=center
- width="30%">
-
- </td>
- </tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
binary files a/docs/glyphs/grid_1.png /dev/null differ
--- a/docs/glyphs/index.html
+++ /dev/null
@@ -1,200 +1,0 @@
-<!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 Glyph Conventions</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType Glyph Conventions
-</h1>
-
-<h2 align=center>
- Version 2.1
-</h2>
-
-<h3 align=center>
- Copyright 1998-2000 David Turner (<a
- href="mailto:[email protected]">[email protected]</a>)<br>
- Copyright 2000 The FreeType Development Team (<a
- href="mailto:[email protected]">[email protected]</a>)
-</h3>
-
-
-<center>
-<table width="70%">
-<tr><td>
-
- <p>This document presents the core conventions used within the FreeType
- library to manage font and glyph data. It is a <em>must-read</em> for all
- developers who need to understand digital typography, especially if you
- want to use the FreeType 2 library in your projects.</p>
-
- <table width="100%">
- <tr valign=center
- bgcolor="#CCCCFF">
- <td align=center>
- <h2>
- Table of Contents
- </h2>
- </td>
- </tr>
- </table>
-
- <center>
- <table width="80%">
- <tr><td>
-
- <h2>
- <a href="glyphs-1.html">I. Basic Typographic Concepts</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-1.html#section-1">1. Font files, format and
- information</a>
- <br>
-
- <a href="glyphs-1.html#section-2">2. Character images and mappings</a>
- <br>
-
- <a href="glyphs-1.html#section-3">3. Character and font metrics</a>
- <br>
- </h3>
- </blockquote>
-
- <h2>
- <a href="glyphs-2.html">II. Glyph outlines</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-2.html#section-1">1. Pixels, points and device
- resolutions</a>
- <br>
-
- <a href="glyphs-2.html#section-2">2. Vectorial representation</a>
- <br>
-
- <a href="glyphs-2.html#section-3">3. Hinting and bitmap rendering</a>
- <br>
- </h3>
- </blockquote>
-
- <h2>
- <a href="glyphs-3.html">III. Glyph metrics</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-3.html#section-1">1. Baseline, pens and layouts</a>
- <br>
-
- <a href="glyphs-3.html#section-2">2. Typographic metrics and
- bounding boxes</a>
- <br>
-
- <a href="glyphs-3.html#section-3">3. Bearings and advances</a>
- <br>
-
- <a href="glyphs-3.html#section-4">4. The effects of grid-fitting</a>
- <br>
-
- <a href="glyphs-3.html#section-5">5. Text widths and bounding box</a>
- <br>
- </h3>
- </blockquote>
-
- <h2>
- <a href="glyphs-4.html">IV. Kerning</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-4.html#section-1">1. Kerning pairs</a>
- <br>
-
- <a href="glyphs-4.html#section-2">2. Applying kerning</a>
- <br>
- </h3>
- </blockquote>
-
- <h2>
- <a href="glyphs-5.html">V. Text processing</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-5.html#section-1">1. Writing simple text strings</a>
- <br>
-
- <a href="glyphs-5.html#section-2">2. Sub-pixel positioning</a>
- <br>
-
- <a href="glyphs-5.html#section-3">3. Simple kerning</a>
- <br>
-
- <a href="glyphs-5.html#section-4">4. Right-to-left layouts</a>
- <br>
-
- <a href="glyphs-5.html#section-5">5. Vertical layouts</a>
- <br>
-
- <a href="glyphs-5.html#section-6">6. WYSIWYG text layouts</a>
- <br>
- </h3>
- </blockquote>
-
- <h2>
- <a href="glyphs-6.html">VI. FreeType Outlines</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-6.html#section-1">1. FreeType outline description
- and structure</a>
- <br>
-
- <a href="glyphs-6.html#section-2">2. Bounding and control box
- computations</a>
- <br>
-
- <a href="glyphs-6.html#section-3">3. Coordinates, scaling, and
- grid-fitting</a>
- <br>
- </h3>
- </blockquote>
-
- <h2>
- <a href="glyphs-7.html">VII. FreeType bitmaps</a>
- </h2>
- <blockquote>
- <h3>
- <a href="glyphs-7.html#section-1">1. Vectorial versus pixel
- coordinates</a>
- <br>
-
- <a href="glyphs-7.html#section-2">2. FreeType bitmap and pixmap
- descriptor</a>
- <br>
-
- <a href="glyphs-7.html#section-3">3. Converting outlines into
- bitmaps and pixmaps</a>
- <br>
- </h3>
- </blockquote>
-
- </td></tr>
- </table>
- </center>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
binary files a/docs/glyphs/points_conic.png /dev/null differ
binary files a/docs/glyphs/points_conic2.png /dev/null differ
binary files a/docs/glyphs/points_cubic.png /dev/null differ
binary files a/docs/glyphs/points_segment.png /dev/null differ
binary files a/docs/glyphs/twlewis1.png /dev/null differ
binary files a/docs/glyphs/twlewis2.png /dev/null differ
binary files a/docs/glyphs/up_flow.png /dev/null differ
binary files a/docs/image/freetype.jpg /dev/null differ
binary files a/docs/tutorial/metrics.png /dev/null differ
binary files a/docs/tutorial/metrics2.png /dev/null differ
--- a/docs/tutorial/step1.html
+++ /dev/null
@@ -1,948 +1,0 @@
-<!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 Tutorial</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType 2.0 Tutorial<br>
- Step 1 -- simple glyph loading
-</h1>
-
-<h3 align=center>
- © 2000 David Turner
- (<a href="mailto:[email protected]">[email protected]</a>)<br>
- © 2000 The FreeType Development Team
- (<a href="http://www.freetype.org">www.freetype.org</a>)
-</h3>
-
-<center>
-<table width="550">
-<tr><td>
-
- <hr>
-
- <h2>
- Introduction
- </h2>
-
- <p>This is the first part of the FreeType 2 tutorial. It will
- teach you to do the following:</p>
-
- <ul>
- <li>initialize the library</li>
- <li>open a font file by creating a new face object</li>
- <li>select a character size in points or in pixels</li>
- <li>load a single glyph image and convert it to a bitmap</li>
- <li>render a very simple string of text</li>
- <li>render a rotated string of text easily</li>
- </ul>
-
- <hr>
-
- <h3>
- 1. Header files
- </h3>
-
- <p>To include the main FreeType header file, say</p>
-
- <font color="blue">
- <pre>
- #include <freetype/freetype.h></pre>
- </font>
-
- <p>in your application code. Note that other files are available in the
- FreeType include directory, most of them being included by
- <tt>freetype.h</tt> and other (internal) files. Some of them will be
- described later in this tutorial.</p>
-
- <hr>
-
- <h3>
- 2. Initialize the library
- </h3>
-
- <p>Simply create a variable of type <tt>FT_Library</tt> named, for
- example, <tt>library</tt>, and call the function
- <tt>FT_Init_FreeType()</tt> as in</p>
-
- <font color="blue">
- <pre>
- #include <freetype/freetype.h>
-
- FT_Library library;
-
- ...
-
- {- ...
- error = FT_Init_FreeType( &library );
- if ( error )
- {- ... an error occurred during library initialization ...
- }
- }</pre>
- </font>
-
- <p>This function is in charge of the following:</p>
-
- <ul>
- <li>
- Creating a new instance of the FreeType 2 library, and set the
- handle <tt>library</tt> to it.
- </li>
- <li>
- Load each module that FreeType knows about in the library. This
- means that by default, your new <tt>library</tt> object is able to
- handle TrueType, Type 1, Windows FON, CID-keyed & OpenType/CFF
- fonts gracefully.
- </li>
- </ul>
-
- <p>As you can see, the function returns an error code, like most others
- in the FreeType API. An error code of 0 <em>always</em> means that
- the operation was successful; otherwise, the value describes the error,
- and <tt>library</tt> is set to <tt>NULL</tt>.</p>
-
- <hr>
-
- <h3>
- 3. Load a font face
- </h3>
-
- <h4>
- a. From a font file
- </h4>
-
- <p>Create a new <em>face</em> object by calling
- <tt>FT_New_Face()</tt>. A <em>face</em> describes a given typeface
- and style. For example, "Times New Roman Regular" and "Times New
- Roman Italic" correspond to two different faces.</p>
-
- <font color="blue">
- <pre>
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
-
-
- error = FT_Init_FreeType( &library );
- if ( error ) { ... }-
- error = FT_New_Face( library,
- "/usr/share/fonts/truetype/arial.ttf",
- 0,
- &face );
- if ( error == FT_Err_Unknown_File_Format )
- {- ... the font file could be opened and read, but it appears
- ... that its font format is unsupported
- }
- else if ( error )
- {- ... another error code means that the font file could not
- ... be opened or read, or that it is broken
- }</pre>
- </font>
-
- <p>As you can certainly imagine, <tt>FT_New_Face()</tt> opens a font
- file, then tries to extract one face from it. Its parameters are</p>
-
- <table cellpadding=5>
- <tr valign="top">
- <td>
- <tt>library</tt>
- </td>
- <td>
- <p>A handle to the FreeType library instance where the face
- object is created</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>filepathname</tt>
- </td>
- <td>
- <p>The font file pathname (a standard C string).</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>face_index</tt>
- </td>
- <td>
- <p>Certain font formats allow several font faces to be embedded
- in a single file.</p>
-
- <p>This index tells which face you want to load. An error will
- be returned if its value is too large.</p>
-
- <p>Index 0 always work though.</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>face</tt>
- </td>
- <td>
- <p>A <em>pointer</em> to the handle that will be set to describe
- the new face object.</p>
-
- <p>It is set to <tt>NULL</tt> in case of error.</p>
- </td>
- </tr>
- </table>
-
- <p>To know how many faces a given font file contains, load its first
- face (use <tt>face_index</tt>=0), then check the value of
- <tt>face->num_faces</tt> which indicates how many faces are embedded
- in the font file.</p>
-
- <h4>
- b. From memory
- </h4>
-
- <p>In the case where you have already loaded the font file in memory,
- you can similarly create a new face object for it by calling
- <tt>FT_New_Memory_Face()</tt> as in</p>
-
- <font color="blue">
- <pre>
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
-
-
- error = FT_Init_FreeType( &library );
- if ( error ) { ... }-
- error = FT_New_Memory_Face( library,
- buffer, /* first byte in memory */
- size, /* size in bytes */
- 0, /* face_index */
- &face );
- if ( error ) { ... }</pre>- </font>
-
- <p>As you can see, <tt>FT_New_Memory_Face()</tt> takes a pointer to
- the font file buffer and its size in bytes instead of a file pathname.
- Other than that, it has exactly the same semantics as
- <tt>FT_New_Face()</tt>.</p>
-
- <h4>
- c. From other sources (compressed files, network, etc.)
- </h4>
-
- <p>There are cases where using a file pathname or preloading the file
- in memory is not sufficient. With FreeType 2, it is possible to
- provide your own implementation of I/O routines.</p>
-
- <p>This is done through the <tt>FT_Open_Face()</tt> function, which
- can be used to open a new font face with a custom input stream, select
- a specific driver for opening, or even pass extra parameters to the
- font driver when creating the object. We advise you to refer to the
- FreeType 2 API reference in order to learn how to use it.</p>
-
- <p>Note that providing a custom stream might also be used to access a
- TrueType font embedded in a Postscript Type 42 wrapper.</p>
-
- <hr>
-
- <h3>
- 4. Accessing face contents
- </h3>
-
- <p>A <em>face object</em> models all information that globally describes
- the face. Usually, this data can be accessed directly by dereferencing
- a handle, like</p>
-
- <table cellpadding=5>
- <tr valign="top">
- <td>
- <tt>face->num_glyphs</tt>
- </td>
- <td>
- <p>Gives the number of <em>glyphs</em> available in the font face.
- A glyph is simply a character image. It doesn't necessarily
- correspond to a <em>character code</em> though.</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>face->flags</tt>
- </td>
- <td>
- <p>A 32-bit integer containing bit flags used to describe some
- face properties. For example, the flag
- <tt>FT_FACE_FLAG_SCALABLE</tt> is used to indicate that the face's
- font format is scalable and that glyph images can be rendered for
- all character pixel sizes. For more information on face flags,
- please read the <a href="#">FreeType 2 API Reference</a>.</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>face->units_per_EM</tt>
- </td>
- <td>
- <p>This field is only valid for scalable formats (it is set
- to 0 otherwise). It indicates the number of font units
- covered by the EM.</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>face->num_fixed_sizes</tt>
- </td>
- <td>
- <p>This field gives the number of embedded bitmap <em>strikes</em>
- in the current face. A <em>strike</em> is a series of glyph
- images for a given character pixel size. For example, a font face
- could include strikes for pixel sizes 10, 12 and 14. Note
- that even scalable font formats can have embedded bitmap
- strikes!</p>
- </td>
- </tr>
- <tr valign="top">
- <td>
- <tt>face->fixed_sizes</tt>
- </td>
- <td>
- <p>This is a pointer to an array of <tt>FT_Bitmap_Size</tt>
- elements. Each <tt>FT_Bitmap_Size</tt> indicates the horizontal
- and vertical <em>pixel sizes</em> for each of the strikes that are
- present in the face.</p>
- </td>
- </tr>
- </table>
-
- <p>For a complete listing of all face properties and fields, please read
- the <a href="#">FreeType 2 API Reference</a>.<p>
-
- <hr>
-
- <h3>
- 5. Setting the current pixel size
- </h3>
-
- <p>FreeType 2 uses <em>size objects</em> to model all information
- related to a given character size for a given face. For example, a size
- object will hold the value of certain metrics like the ascender or text
- height, expressed in 1/64th of a pixel, for a character size of
- 12 points.</p>
-
- <p>When the <tt>FT_New_Face()</tt> function is called (or one of its
- cousins), it <em>automatically</em> creates a new size object for the
- returned face. This size object is directly accessible as
- <tt>face->size</tt>.</p>
-
- <p><em>A single face object can deal with one or more size objects at a
- time; however, this is something that few programmers really need to do.
- We have thus have decided to simplify the API for the most common use
- (i.e. one size per face), while keeping this feature available through
- additional functions.</em></p>
-
- <p>Before a glyph can be loaded, the size object must be set up. To do
- that, simply call <tt>FT_Set_Char_Size()</tt>. Here is an example where
- the character size is set to 16pt for a 300x300 dpi device:</p>
-
- <font color="blue">
- <pre>
- error = FT_Set_Char_Size(
- face, /* handle to face object */
- 0, /* char_width in 1/64th of points */
- 16 * 64, /* char_height in 1/64th of points */
- 300, /* horizontal device resolution */
- 300 ); /* vertical device resolution */</pre>
- </font>
-
- <p>You will notice that</p>
-
- <ul>
- <li>
- The character width and heights are specified in 1/64th of points.
- A point is a <em>physical</em> distance, equaling 1/72th of an inch;
- it is not a pixel.
- </li>
- <li>
- Horizontal and vertical device resolutions are expressed in
- <em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or
- 96 dpi for display devices like the screen. The resolution is
- used to compute the character pixel size from the character point
- size.
- </li>
- <li>
- A value of 0 for the character width means <em>same as
- character height</em>, a value of 0 for the character height
- means <em>same as character width</em>. Otherwise, it is possible
- to specify different char widths and heights.
- </li>
- <li>
- Using a value of 0 for the horizontal or vertical resolution
- means 72 dpi, which is the default.
- </li>
- <li>
- The first argument is a handle to a face object, not a size object.
- This behaviour must be seen as a convenience.
- </li>
- </ul>
-
- <p>This function computes the character pixel size that corresponds to
- the character width and height and device resolutions. However, if you
- want to specify the pixel sizes yourself, you can simply call
- <tt>FT_Set_Pixel_Sizes()</tt>, as in</p>
-
- <font color="blue">
- <pre>
- error = FT_Set_Pixel_Sizes(
- face, /* handle to face object */
- 0, /* pixel_width */
- 16 ); /* pixel_height */</pre>
- </font>
-
- <p>This example will set the character pixel sizes to 16x16 pixels.
- As previously, a value of 0 for one of the dimensions means
- <em>same as the other</em>.</p>
-
- <p>Note that both functions return an error code. Usually, an error
- occurs with a fixed-size font format (like FNT or PCF) when trying to
- set the pixel size to a value that is not listed in the
- <tt>face->fixed_sizes</tt> array.</p>
-
- <hr>
-
- <h3>
- 6. Loading a glyph image
- </h3>
-
- <h4>
- a. Converting a character code into a glyph index
- </h4>
-
- <p>Usually, an application wants to load a glyph image based on its
- <em>character code</em>, which is a unique value that defines the
- character for a given <em>encoding</em>. For example, the character
- code 65 in ASCII encoding represents letter `A'.</p>
-
- <p>A face object contains one or more tables, called
- <em>charmaps</em>, that are used to convert character codes to glyph
- indices. For example, most TrueType fonts contain two charmaps. One
- is used to convert Unicode character codes to glyph indices, the other
- is used to convert Apple Roman encoding into glyph indices. Such
- fonts can then be used either on Windows (which uses Unicode) and
- Macintosh (which uses Apple Roman usually). Note also that a given
- charmap might not map to all the glyphs present in the font.</p>
-
- <p>By default, when a new face object is created, it lists all the
- charmaps contained in the font face and selects the one that supports
- Unicode character codes if it finds one. Otherwise, it tries to find
- support for Latin-1, then ASCII.</p>
-
- <p>We will describe later how to look for specific charmaps in a face.
- For now, we will assume that the face contains at least a Unicode
- charmap that was selected during <tt>FT_New_Face()</tt>. To convert a
- Unicode character code to a font glyph index, we use
- <tt>FT_Get_Char_Index()</tt> as in</p>
-
- <font color="blue">
- <pre>
- glyph_index = FT_Get_Char_Index( face, charcode );</pre>
- </font>
-
- <p>This will look up the glyph index corresponding to the given
- <tt>charcode</tt> in the charmap that is currently selected for the
- face.
-
- <p>Note that this is one of the rare FreeType functions that do not
- return an error code. If a given character code has no glyph image in
- the face, the value 0 is returned. By convention, it always
- corresponds to a special glyph image called the <em>missing
- glyph</em>, which usually is represented as a box or a space.</p>
-
- <h4>
- b. Loading a glyph from the face
- </h4>
-
- <p>Once you have a glyph index, you can load the corresponding glyph
- image. The latter can be stored in various formats within the font
- file. For fixed-size formats like FNT or PCF, each image is a bitmap.
- Scalable formats like TrueType or Type 1 use vectorial shapes,
- named <em>outlines</em>, to describe each glyph. Some formats may have
- even more exotic ways of representing glyphs (e.g. MetaFont).
- Fortunately, FreeType 2 is flexible enough to support any kind of
- glyph format through a simple API.</p>
-
- <p>The glyph image is always stored in a special object called a
- <em>glyph slot</em>. As its name suggests, a glyph slot is a
- container that is able to hold one glyph image at a time, be it a
- bitmap, an outline, or something else. Each face object has a single
- glyph slot object that can be accessed as <tt>face->glyph</tt>.</p>
-
- <p>Loading a glyph image into the slot is performed by calling
- <tt>FT_Load_Glyph()</tt> as in</p>
-
- <font color="blue">
- <pre>
- error = FT_Load_Glyph(
- face, /* handle to face object */
- glyph_index, /* glyph index */
- load_flags ); /* load flags, see below */</pre>
- </font>
-
- <p>The <tt>load_flags</tt> value is a set of bit flags used to
- indicate some special operations. The default value
- <tt>FT_LOAD_DEFAULT</tt> is 0.</p>
-
- <p>This function will try to load the corresponding glyph image from
- the face. Basically, this means that</p>
-
- <ul>
- <li>
- <p>If a bitmap is found for the corresponding glyph and pixel
- size, it will be loaded into the slot. Embedded bitmaps are
- always favored over native image formats, because we assume that
- they are higher-quality versions of the same glyph. This can be
- changed by using the <tt>FT_LOAD_NO_BITMAP</tt> flag.</p>
- </li>
- <li>
- <p>Otherwise, a native image for the glyph will be loaded. It
- will also be scaled to the current pixel size as well as hinted
- for certain formats like TrueType and Type 1.</p>
- </li>
- </ul>
-
- <p>The field <tt>glyph->format</tt> describes the format used to store
- the glyph image in the slot. If it is not
- <tt>ft_glyph_format_bitmap</tt>, it is possible to immedialy convert
- it to a bitmap through <tt>FT_Render_Glyph()</tt>, as in</p>
-
- <font color="blue">
- <pre>
- error = FT_Render_Glyph(
- face->glyph, /* glyph slot */
- render_mode ); /* render mode */</pre>
- </font>
-
- <p>The parameter <tt>render_mode</tt> specifies how to render the
- glyph image. Set it <tt>ft_render_mode_normal</tt> to render a
- high-quality anti-aliased (256 gray levels) bitmap. 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>glyph->bitmap</tt> (a simple bitmap descriptor), and
- position it with <tt>glyph->bitmap_left</tt> and
- <tt>glyph->bitmap_top</tt>.</p>
-
- <p>Note that <tt>bitmap_left</tt> is the horizontal distance from the
- current pen position to the left-most border of the glyph bitmap,
- while <tt>bitmap_top</tt> is the vertical distance from the pen
- position (on the baseline) to the top-most border of the glyph bitmap.
- <em>It is positive to indicate an upwards distance</em>.</p>
-
- <p>The second part of the tutorial describes the contents of a glyph
- slot and how to access specific glyph information (including
- metrics).</p>
-
- <h4>
- c. Using other charmaps
- </h4>
-
- <p>As said before, when a new face object is created, it will look for
- a Unicode, Latin-1, or ASCII charmap and select it. The currently
- selected charmap is accessed via <tt>face->charmap</tt>. This field
- is <tt>NULL</tt> if no charmap is selected, which typically happens
- when you create a new <tt>FT_Face</tt> object from a font file that
- doesn't contain an ASCII, Latin-1, or Unicode charmap (rare
- stuff).</p>
-
- <p>There are two ways to select a different charmap with
- FreeType 2. The easiest is if the encoding you need already has
- a corresponding enumeration defined in <tt>freetype/freetype.h</tt>,
- as <tt>ft_encoding_big5</tt>. In this case, you can simply call
- <tt>FT_Select_CharMap()</tt> as in</p>
-
- <font color="blue"><pre>
- error = FT_Select_CharMap(
- face, /* target face object */
- ft_encoding_big5 ); /* encoding */</pre>
- </font>
-
- <p>Another way is to manually parse the list of charmaps for the face;
- this is accessible through the fields <tt>num_charmaps</tt> and
- <tt>charmaps</tt> (notice the final 's') of the face object. As
- expected, the first is the number of charmaps in the face, while the
- second is <em>a table of pointers to the charmaps</em> embedded in the
- face.</p>
-
- <p>Each charmap has a few visible fields used to describe it more
- precisely. Mainly, one will look at <tt>charmap->platform_id</tt> and
- <tt>charmap->encoding_id</tt> which define a pair of values that can
- be used to describe the charmap in a rather generic way.</p>
-
- <p>Each value pair corresponds to a given encoding. For example, the
- pair (3,1) corresponds to Unicode (on the Windows platform). A list
- of such pairs is defined in the TrueType specification, but you can
- also use the file <tt><freetype/ttnameid.h></tt> which defines
- several helpful constants to deal with them.</p>
-
- <p>Note that some pid/eid pairs are <em>artificial</em>; such values
- have been created by FreeType to identify platforms resp. encodings
- not covered by the original TrueType specification.</p>
-
- <p>To look up a specific encoding you need to find a corresponding
- value pair in the specification, then look for it in the
- <tt>charmaps</tt> list. Bear in mind that some encodings correspond
- to several values pairs (yes, it's a real mess, but blame Apple and
- Microsoft on such stupidity). Here some code to do it:</p>
-
- <font color="blue">
- <pre>
- FT_CharMap found = 0;
- FT_CharMap charmap;
- int n;
-
-
- for ( n = 0; n < face->num_charmaps; n++ )
- {- charmap = face->charmaps[n];
- if ( charmap->platform_id == my_platform_id &&
- charmap->encoding_id == my_encoding_id )
- {- found = charmap;
- break;
- }
- }
-
- if ( !found ) { ... }-
- /* now, select the charmap for the face object */
- error = FT_Set_CharMap( face, found );
- if ( error ) { ... }</pre>- </font>
-
- <p>Once a charmap has been selected, either through
- <tt>FT_Select_CharMap()</tt> or <tt>FT_Set_CharMap()</tt>, it is used
- by all subsequent calls to <tt>FT_Get_Char_Index()</tt>.</p>
-
- <h4>
- d. Glyph transformations
- </h4>
-
- <p>It is possible to specify an affine transformation to be applied to
- glyph images when they are loaded. Of course, this will only work for
- scalable (vectorial) font formats.</p>
-
- <p>To do that, simply call <tt>FT_Set_Transform()</tt>, as in</p>
-
- <font color="blue">
- <pre>
- error = FT_Set_Transform(
- face, /* target face object */
- &matrix, /* pointer to 2x2 matrix */
- &delta ); /* pointer to 2d vector */</pre>
- </font>
-
- <p>This function will set the current transformation for a given face
- object. Its second parameter is a pointer to an <tt>FT_Matrix</tt>
- structure that describes a 2x2 affine matrix. The third
- parameter is a pointer to an <tt>FT_Vector</tt> structure that
- describes a simple 2d vector that is used to translate the glyph
- image <em>after</em> the 2x2 transformation.</p>
-
- <p>Note that the matrix pointer can be set to <tt>NULL</tt>, in which
- case the identity transformation will be used. Coefficients of the
- matrix are otherwise in 16.16 fixed float units.</p>
-
- <p>The vector pointer can also be set to <tt>NULL</tt> in which case a
- delta vector 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>The transformation 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
- transformation, because hints will have been computed differently
- (unless hints have been disabled, of course).</em></p>
-
- <p>If you ever need to use a non-orthogonal transformation with
- optimal hints, you first need to decompose your transformation 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
- <tt>FT_Set_Transform()</tt>. 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
- transformation will produce an error.</p>
-
- <hr>
-
- <h3>
- 7. Simple text rendering
- </h3>
-
- <p>We will now present a very simple example used to render a string of
- 8-bit Latin-1 text, assuming a face that contains a Unicode charmap</p>
-
- <p>The idea is to create a loop that will, on each iteration, load one
- glyph image, convert it to an anti-aliased bitmap, draw it on the target
- surface, then increment the current pen position.</p>
-
- <h4>
- a. basic code
- </h4>
-
- <p>The following code performs our simple text rendering with the
- functions previously described.</p>
-
- <font color="blue">
- <pre>
- FT_GlyphSlot slot = face->glyph; /* a small shortcut */
- int pen_x, pen_y, n;
-
-
- .. initialize library ..
- .. create face object ..
- .. set character size ..
-
- pen_x = 300;
- pen_y = 200;
-
- for ( n = 0; n < num_chars; n++ )
- {- FT_UInt glyph_index;
-
-
- /* retrieve glyph index from character code */
- glyph_index = FT_Get_Char_Index( face, text[n] );
-
- /* load glyph image into the slot (erase previous one) */
- error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT );
- if ( error ) continue; /* ignore errors */
-
- /* convert to an anti-aliased bitmap */
- error = FT_Render_Glyph( face->glyph, ft_render_mode_normal );
- if ( error ) continue;
-
- /* now, draw to our target surface */
- my_draw_bitmap( &slot->bitmap,
- pen_x + slot->bitmap_left,
- pen_y - slot->bitmap_top );
-
- /* increment pen position */
- pen_x += slot->advance.x >> 6;
- pen_y += slot->advance.y >> 6; /* not useful for now */
- }</pre>
- </font>
-
- <p>This code needs a few explanations:</p>
-
- <ul>
- <li>
- We define a handle named <tt>slot</tt> that points to the face
- object's glyph slot. (The type <tt>FT_GlyphSlot</tt> is a
- pointer.) This is a convenience to avoid using
- <tt>face->glyph->XXX</tt> every time.
- </li>
- <li>
- We increment the pen position with the vector
- <tt>slot->advance</tt>, which corresponds to the glyph's
- <em>advance width</em> (also known as its <em>escapement</em>).
- The advance vector is expressed in 1/64th of pixels, and is
- truncated to integer pixels on each iteration.
- </li>
- <li>
- The function <tt>my_draw_bitmap()</tt> is not part of FreeType but
- must be provided by the application to draw the bitmap to the
- target surface. In this example, it takes a pointer to an
- <tt>FT_Bitmap</tt> descriptor and the position of its top-left
- corner as arguments.
- </li>
- <li>
- The value of <tt>slot->bitmap_top</tt> is positive for an
- <em>upwards</em> vertical distance. Assuming that the coordinates
- taken by <tt>my_draw_bitmap()</tt> use the opposite convention
- (increasing Y corresponds to downwards scanlines), we substract it
- to <tt>pen_y</tt> instead of adding it.
- </li>
- </ul>
-
- <h4>b. refined code</h4>
-
- <p>The following code is a refined version of the example above. It
- uses features and functions of FreeType 2 that have not yet been
- introduced, and which will be explained below.</p>
-
- <font color="blue">
- <pre>
- FT_GlyphSlot slot = face->glyph; /* a small shortcut */
- FT_UInt glyph_index;
- int pen_x, pen_y, n;
-
-
- .. initialize library ..
- .. create face object ..
- .. set character size ..
-
- pen_x = 300;
- pen_y = 200;
-
- 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 );
- if ( error ) continue; /* ignore errors */
-
- /* now, draw to our target surface */
- my_draw_bitmap( &slot->bitmap,
- pen_x + slot->bitmap_left,
- pen_y - slot->bitmap_top );
-
- /* increment pen position */
- pen_x += slot->advance.x >> 6;
- }</pre>
- </font>
-
- <p>We have reduced the size of our code, but it does exactly the same
- thing.</p>
-
- <ul>
- <li>
- <p>We use the function <tt>FT_Load_Char()</tt> instead of
- <tt>FT_Load_Glyph()</tt>. As you probably imagine, it is
- equivalent to calling <tt>FT_Get_Char_Index()</tt> followed by
- <tt>FT_Get_Load_Glyph()</tt>.</p>
- </li>
- <li>
- <p>We do not use <tt>FT_LOAD_DEFAULT</tt> for the loading mode but
- the bit flag <tt>FT_LOAD_RENDER</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> explicitly but is strictly
- equivalent.</p>
-
- <p>Note that you can also specify that you want a monochrome
- bitmap by using the <tt>FT_LOAD_MONOCHROME</tt> load flag
- instead.</p>
- </li>
- </ul>
-
- <h4>c. more advanced rendering</h4>
-
- <p>We now render transformed text (for example through a rotation).
- To do that we use <tt>FT_Set_Transform()</tt>:</p>
-
- <font color="blue">
- <pre>
- FT_GlyphSlot slot = face->glyph; /* a small shortcut */
- FT_Matrix matrix; /* transformation matrix */
- FT_UInt glyph_index;
- FT_Vector pen; /* untransformed origin */
- int n;
-
-
- .. initialize library ..
- .. create face object ..
- .. set character size ..
-
- /* set up matrix */
- matrix.xx = (FT_Fixed)( cos( angle ) * 0x10000L );
- matrix.xy = (FT_Fixed)(-sin( angle ) * 0x10000L );
- matrix.yx = (FT_Fixed)( sin( angle ) * 0x10000L );
- matrix.yy = (FT_Fixed)( cos( angle ) * 0x10000L );
-
- /* the pen position in 26.6 cartesian space coordinates */
- pen.x = 300 * 64;
- pen.y = ( my_target_height - 200 ) * 64;
-
- for ( n = 0; n < num_chars; n++ )
- {- /* set transformation */
- 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 );
- if ( error ) continue; /* ignore errors */
-
- /* now, draw to our target surface (convert position) */
- my_draw_bitmap( &slot->bitmap,
- slot->bitmap_left,
- my_target_height - slot->bitmap_top );
-
- /* increment pen position */
- pen.x += slot->advance.x;
- pen.y += slot->advance.y;
- }</pre>
- </font>
-
- <p>Notes:</p>
-
- <ul>
- <li>
- We now use a vector of type <tt>FT_Vector</tt> to store the pen
- position, with coordinates expressed as 1/64th of pixels, hence a
- multiplication. The position is expressed in cartesian space.
- </li>
- <li>
- In FreeType, glyph images are always loaded, transformed, and
- described in the cartesian coordinate system (which means that
- increasing Y corresponds to upper scanlines), unlike the
- system typically used for bitmaps (where the top-most scanline has
- coordinate 0). We must thus convert between the two systems
- when we define the pen position, and when we compute the top-left
- position of the bitmap.
- </li>
- <li>
- We apply the transformation matrix on each glyph to indicate
- rotation as well as a delta vector that will move the transformed
- image to the current pen position (in cartesian space, not bitmap
- space).
- </li>
- <li>
- The advance width is always returned transformed, which is why it
- can be directly added to the current pen position. Note that it
- is <em>not</em> rounded this time.
- </li>
- </ul>
-
- <p>It is important to note that, while this example is a bit more
- complex than the previous one, it is strictly equivalent for the case
- where the transformation is the identity. Hence it can be used as a
- replacement (but a more powerful one).</p>
-
- <p>It has, however, a few shortcomings that we will explain, and
- solve, in the next part of this tutorial.</p>
-
- <hr>
-
- <h3>
- Conclusion
- </h3>
-
- <p>In this first section, you have learned the basics of FreeType 2
- as well as sufficient knowledge how to render rotated text.</p>
-
- <p>The next part will dive into more details of the API in order to let
- you access glyph metrics and images directly, how to deal with scaling,
- hinting, kerning, etc.</p>
-
- <p>The third part will discuss issues like modules, caching, and a few
- other advanced topics like how to use multiple size objects with a
- single face.</p>
-
-</td></tr>
-</table>
-</center>
-
-</body>
-</html>
--- a/docs/tutorial/step2.html
+++ /dev/null
@@ -1,1607 +1,0 @@
-<!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 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:[email protected]">[email protected]</a>)<br>
- © 2000 The FreeType Development Team
- (<a href="http://www.freetype.org">www.freetype.org</a>)
-</h3>
-
-<center>
-<table width="550">
-<tr><td>
-
- <hr>
-
- <h2>
- Introduction
- </h2>
-
- <p>This is the second part 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 if 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>FT_HAS_VERTICAL(face)</tt>, which is true if vertical metrics are
- available.</p>
-
- <p>Individual glyph metrics can be accessed by first loading the glyph
- in a face's glyph slot, then using the <tt>face->glyph->metrics</tt>
- structure. This will be described later; for now, we observe that it
- contains the following fields:</p>
-
- <center>
- <table width="90%" cellpadding=5>
- <tr valign=top>
- <td>
- <tt>width</tt>
- </td>
- <td>
- This is the width of the glyph image's bounding box. It is
- independent of the layout direction.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>height</tt>
- </td>
- <td>
- This is the height of the glyph image's bounding box. It is
- independent of the layout direction.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>horiBearingX</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>horiBearingY</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>horiAdvance</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>vertBearingX</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>vertBearingY</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>vertAdvance</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- </table>
- </center>
-
- <p><em>As not all fonts do contain vertical metrics, the values of
- <tt>vertBearingX</tt>, <tt>vertBearingY</tt>, and <tt>vertAdvance</tt>
- should not be considered reliable if <tt>FT_HAS_VERTICAL(face)</tt> is
- false.</em></p>
-
- <p>The following graphics illustrate the metrics more clearly. First
- horizontal metrics, where the baseline is the horizontal axis:</p>
-
- <center>
- <img src="metrics.png"
- alt="horizontal metrics layout"
- 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"
- alt="vertical metrics layout"
- width=294 height=278>
- </center>
-
- <p>The metrics found in <tt>face->glyph->metrics</tt> are normally
- expressed in 26.6 pixel format (i.e 1/64th of pixels), unless you use
- the <tt>FT_LOAD_NO_SCALE</tt> flag when calling <tt>FT_Load_Glyph()</tt>
- or <tt>FT_Load_Char()</tt>. In that case, the metrics will be expressed
- in original font units.</p>
-
- <p>The glyph slot object has a few other interesting fields that will
- ease a developer's work. You can access them through
- <tt>face->glyph->???</tt>:</p>
-
- <center>
- <table width="90%" cellpadding=5>
- <tr valign=top>
- <td>
- <tt>advance</tt>
- </td>
- <td>
- This field is an <tt>FT_Vector</tt> which holds the transformed
- advance value for the glyph. This is useful if you are using a
- transformation through <tt>FT_Set_Transform()</tt>, as shown in the
- rotated text example of the previous part. Other than that, its
- value is by default (metrics.horiAdvance,0), unless you specify
- <tt>FT_LOAD_VERTICAL</tt> when loading the glyph image; it will then
- be (0,metrics.vertAdvance).
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>linearHoriAdvance</tt>
- </td>
- <td>
- 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 used to perform pseudo
- device-independent text layouts.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>linearVertAdvance</tt>
- </td>
- <td>
- This is the same thing as <tt>linearHoriAdvance</tt> for the glyph's
- vertical advance height. Its value is only reliable if the font
- face contains vertical metrics.
- </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> afterwards. 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. For example, you want to cache images within your
- application, or you want to apply additional transformations 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:</p>
-
- <font color="blue">
- <pre>
- #include <freetype/ftglyph.h></pre>
- </font>
-
- <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 some code
- that shows how to do it.</p>
-
- <font color="blue">
- <pre>
- FT_Glyph glyph; /* handle to glyph image */
-
-
- ...
- error = FT_Load_Glyph( face, glyph, FT_LOAD_NORMAL );
- if ( error ) { .... }-
- error = FT_Get_Glyph( face->glyph, &glyph );
- if ( error ) { .... }</pre>- </font>
-
- <p>As can be seen, we have</p>
-
- <ul>
- <li>
- created a variable, named <tt>glyph</tt>, of type
- <tt>FT_Glyph</tt>. This is a handle (pointer) to an individual
- glyph image,
- </li>
- <li>
- 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 transform it later,
- </li>
- <li>
- copied the glyph image from the slot into a new <tt>FT_Glyph</tt>
- object by calling <tt>FT_Get_Glyph()</tt>. This function returns
- an error code and sets <tt>glyph</tt>.
- </li>
- </ul>
-
- <p>It is important to note that the extracted glyph is in the same
- format as the original one that is still in the slot. For example, if
- we are 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>glyph->format</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>FT_Done_Glyph()</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>glyph->advance</tt>.</p>
-
- <p><em>Note that unlike other FreeType objects, the library doesn't
- keep a list of all allocated glyph objects. This means you will need
- to destroy them yourself, instead of relying on
- <tt>FT_Done_FreeType()</tt> to do all the clean-up.</em></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 <tt>ft_glyph_format_bitmap</tt>), it is possible to transform the
- image anytime by a call to <tt>FT_Glyph_Transform()</tt>.</p>
-
- <p>You can also copy a single glyph image with
- <tt>FT_Glyph_Copy()</tt>. Here some example code:</p>
-
- <font color="blue">
- <pre>
- FT_Glyph glyph, glyph2;
- FT_Matrix matrix;
- FT_Vector delta;
-
-
- ...
- .. load glyph image in "glyph" ..
-
- /* copy glyph to glyph2 */
- error = FT_Glyph_Copy( glyph, &glyph2 );
- if ( error ) { ... could not copy (out of memory) }-
- /* translate "glyph" */
- delta.x = -100 * 64; /* coordinates are in 26.6 pixels */
- delta.y = 50 * 64;
-
- FT_Glyph_Transform( glyph, 0, &delta );
-
- /* transform glyph2 (horizontal shear) */
- matrix.xx = 0x10000L;
- matrix.xy = 0;
- matrix.yx = 0.12 * 0x10000L;
- matrix.yy = 0x10000L;
-
- FT_Glyph_Transform( glyph2, &matrix, 0 );</pre>
- </font>
-
- <p>Note that the 2x2 transformation 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), using the <tt>FT_Glyph_Get_CBox()</tt>
- function:</p>
-
- <font color="blue">
- <pre>
- FT_BBox bbox;
-
-
- ...
- FT_Glyph_Get_CBox( glyph, <em>bbox_mode</em>, &bbox );</pre>
- </font>
-
- <p>Coordinates are relative to the glyph origin, i.e. (0,0), using the
- Y upwards convention. This function takes a special argument,
- <tt>bbox_mode</tt>, to indicate how box coordinates are expressed. If
- <tt>bbox_mode</tt> is set to <tt>ft_glyph_bbox_subpixels</tt>, the
- coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels).
-
- <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 it in integer or 26.6 pixels with</p>
-
- <font color="blue">
- <pre>
- width = bbox.xMax - bbox.xMin;
- height = bbox.yMax - bbox.yMin;</pre>
- </font>
-
- <p>Note also that for 26.6 coordinates, if
- <tt>ft_glyph_bbox_gridfit</tt> is set in <tt>bbox_mode</tt>, the
- coordinates will also be grid-fitted, which corresponds to</p>
-
- <font color="blue">
- <pre>
- bbox.xMin = FLOOR(bbox.xMin)
- bbox.yMin = FLOOR(bbox.yMin)
- bbox.xMax = CEILING(bbox.xMax)
- bbox.yMax = CEILING(bbox.yMax)</pre>
- </font>
-
- <p>The default value for <tt>bbox_mode</tt> is
- <tt>ft_glyph_bbox_pixels</tt> (i.e. integer, grid-fitted pixel
- coordinates). Please check the API reference of
- <tt>FT_Glyph_Get_CBox()</tt> for other possible values.</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
- conveniently cached or transformed it. This can be done easily with
- the <tt>FT_Glyph_To_Bitmap()</tt> function:</p>
-
- <font color="blue">
- <pre>
- FT_Vector origin;
-
-
- origin.x = 32; /* 1/2 pixel in 26.6 format */
- origin.y = 0;
-
- error = FT_Glyph_To_Bitmap( &glyph,
- <em>render_mode</em>,
- &origin,
- 1 ); /* destroy orig. image == true */</pre>
- </font>
-
- <p>Some details on this function's parameters:</p>
-
- <ul>
- <li>
- The first parameter is <em>the address of the source glyph's
- handle</em>. When the function is called, it reads it to access
- the source glyph object. After the call, the handle will point to
- a <em>new</em> glyph object that contains the rendered bitmap.
- </li>
- <li>
- 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.
- </li>
- <li>
- 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.
- </li>
- <li>
- The last parameter is a Boolean to indicate whether 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).
- </li>
- </ul>
-
- <p>The new glyph object always contains a bitmap (when no error is
- returned), and you must <em>typecast</em> its handle to the
- <tt>FT_BitmapGlyph</tt> type in order to access its contents. This
- type is a sort of <em>subclass</em> of <tt>FT_Glyph</tt> that contains
- additional fields:</p>
-
- <center>
- <table width="90%" cellpadding=5>
- <tr valign=top>
- <td>
- <tt>left</tt>
- </td>
- <td>
- Just like the <tt>bitmap_left</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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>top</tt>
- </td>
- <td>
- Just like the <tt>bitmap_top</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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>bitmap</tt>
- </td>
- <td>
- This is a bitmap descriptor for the glyph object, just like the
- <tt>bitmap</tt> field in a glyph slot.
- </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
- pixel format or in design <em>font units</em> 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 part of the tutorial. You
- can access them directly as fields of an <tt>FT_Face</tt> handle.</p>
-
- <p>However, you need to check that the font face's format is scalable
- before using them. This can be done with the macro
- <tt>FT_IS_SCALABLE(face)</tt> which returns true if we have a scalable
- format.</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>units_per_EM</tt>
- </td>
- <td>
- 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 part. Its value usually
- is 2048 (for TrueType) or 1000 (for Type 1), but
- other values are possible too. It is set to 1 for fixed-size
- formats like FNT/FON/PCF/BDF.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>global_bbox</tt>
- </td>
- <td>
- 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. This is not necessarily the smallest
- bounding box which is possible.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>ascender</tt>
- </td>
- <td>
- The ascender is the vertical distance from the horizontal baseline
- to the height of the highest character 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 is the
- ascent of the highest accented character, and finally, other
- formats define it as being equal to <tt>global_bbox.yMax</tt>.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>descender</tt>
- </td>
- <td>
- The descender is the vertical distance from the horizontal
- baseline to the depth of the lowest character 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 is the
- ascent of the lowest accented character, and finally, other
- formats define it as being equal to <tt>global_bbox.yMin</tt>.
- <em>This field is usually negative.</em>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>text_height</tt>
- </td>
- <td>
- This field is 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 as absolute values. There is also no guarantee
- that no glyphs can extend above or below subsequent baselines when
- using this distance.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>max_advance_width</tt>
- </td>
- <td>
- 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>
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>max_advance_height</tt>
- </td>
- <td>
- Same as <tt>max_advance_width</tt> but for vertical text layout.
- It is only available in fonts providing vertical glyph metrics.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>underline_position</tt>
- </td>
- <td>
- When displaying or rendering underlined text, this value
- corresponds to the vertical position, relative to the baseline, of
- the underline bar. It normally is negative (as it is below the
- baseline).
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>underline_thickness</tt>
- </td>
- <td>
- When displaying or rendering underlined text, this value
- corresponds to the vertical thickness of the underline.
- </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 scaled versions of some of the
- global metrics described above. They can be accessed directly through
- the <tt>face->size->metrics</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 are expressed in 26.6 pixel format.</p>
-
- <center>
- <table width="90%" cellpadding=5>
- <tr valign=top>
- <td>
- <tt>ascender</tt>
- </td>
- <td>
- This is the scaled version of the original design ascender.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>descender</tt>
- </td>
- <td>
- This is the scaled version of the original design descender.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>height</tt>
- </td>
- <td>
- The scaled version of the original design text height. This is
- probably the only field you should really use in this structure.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>max_advance</tt>
- </td>
- <td>
- This is the scaled version of the original design max advance.
- </td>
- </tr>
- </table>
- </center>
-
- <p>Note that the <tt>face->size->metrics</tt> structure contains other
- fields that are used to scale design coordinates to device space.
- They are described below.</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>Not 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 <tt>.pfa</tt> or <tt>.pfb</tt>, and where kerning
- metrics can be found in an additional file with extension
- <tt>.afm</tt> or <tt>.pfm</tt>.</p>
-
- <p>FreeType 2 allows you to deal with this by providing the
- <tt>FT_Attach_File()</tt> and <tt>FT_Attach_Stream()</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>
-
- <font color="blue">
- <pre>
- 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 ..
- }</pre>
- </font>
-
- <p>Note that <tt>FT_Attach_Stream()</tt> is similar to
- <tt>FT_Attach_File()</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 data is entirely font format specific.</p>
-
- <p>FreeType 2 allows you to retrieve the kerning information
- between two glyphs through the <tt>FT_Get_Kerning()</tt> function,
- whose interface looks like</p>
-
- <font color="blue">
- <pre>
- FT_Vector kerning;
-
-
- ...
- error = FT_Get_Kerning(
- face, /* handle to face object */
- left, /* left glyph index */
- right, /* right glyph index */
- <em>kerning_mode</em>, /* kerning mode */
- &kerning ); /* target vector */</pre>
- </font>
-
- <p>As can be seen, 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 <em>kerning mode</em>, and
- a pointer to a destination vector that receives the corresponding
- distances.</p>
-
- <p>The kerning mode is very similar to <tt>bbox_mode</tt> described in
- a previous part. It is an enumeration value that indicates how the
- kerning distances are expressed in the target vector.</p>
-
- <p>The default value <tt>ft_kerning_mode_default</tt> (which has
- value 0) 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>ft_kerning_mode_unfitted</tt> corresponds to kerning
- distances expressed in 26.6 unfitted pixels (i.e. that do not
- correspond to integer coordinates). It is the design kerning distance
- that is scaled without rounding.</p>
-
- <p>Finally, the value <tt>ft_kerning_mode_unscaled</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 part.</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 bidirectional text, or when writing right-to-left
- text.</p>
-
- <hr>
-
- <h3>
- 4. Simple text rendering: kerning + centering
- </h3>
-
- <p>In order to show off what we have just learned, we will now modify
- the example code that was provided in the first part 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 are still dealing with a left-to-right script like
- Latin. We 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;
-
-
- .. initialize 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++ )
- {- /* convert character code to glyph index */
- glyph_index = FT_Get_Char_Index( face, text[n] );
-
- /* retrieve kerning distance and move pen position */
- 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;
- }
-
- /* load glyph image into the slot (erase previous one) */
- error = FT_Load_Glyph( face, glyph_index, FT_LOAD_RENDER );
- if ( error ) continue; /* ignore errors */
-
- /* now, draw to our target surface */
- my_draw_bitmap( &slot->bitmap,
- pen_x + slot->bitmap_left,
- pen_y - slot->bitmap_top );
-
- /* increment pen position */
- pen_x += slot->advance.x >> 6;
-
- /* record current glyph index */
- previous = glyph_index;
- }</pre>
- </font>
-
- <p>We are done. Notice that</p>
-
- <ul>
- <li>
- As kerning is determined from glyph indices, we need to
- explicitly convert our character code into a glyph index, then
- later call <tt>FT_Load_Glyph()</tt> instead of
- <tt>FT_Load_Char()</tt>.
- </li>
- <li>
- We use a Boolean named <tt>use_kerning</tt> which is set with the
- result of the macro <tt>FT_HAS_KERNING(face)</tt>. It is
- certainly faster not to call <tt>FT_Get_Kerning()</tt> if we
- know that the font face does not contain kerning information.
- </li>
- <li>
- We move the position of the pen <em>before</em> a new glyph is
- drawn.
- </li>
- <li>
- We did initialize the variable <tt>previous</tt> with the
- value 0, which always correspond to the <em>missing
- glyph</em> (also called <tt>.notdef</tt> in the PostScript world).
- There is never any kerning distance associated with this glyph.
- </li>
- <li>
- We do not check the error code returned by
- <tt>FT_Get_Kerning()</tt>. This is because the function always
- set <tt>delta</tt> to (0,0) when an error occurs.
- </li>
- </ul>
-
- <h4>
- b. Centering
- </h4>
-
- <p>Our code becomes more interesting but it is still a bit too simple
- for normal uses. For example, the position of the pen is determined
- before we do the rendering if in a real-life 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>As a consequence we are 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 will be shown, this has many
- advantages.</p>
-
- <p>We 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; /* a small shortcut */
- FT_UInt glyph_index;
- FT_Bool use_kerning;
- FT_UInt previous;
- int pen_x, pen_y, n;
-
- FT_Glyph glyphs[MAX_GLYPHS]; /* glyph image */
- FT_Vector pos [MAX_GLYPHS]; /* glyph position */
- FT_UInt num_glyphs;
-
-
- .. initialize library ..
- .. create face object ..
- .. set character size ..
-
- pen_x = 0; /* start at (0,0)! */
- pen_y = 0;
-
- num_glyphs = 0;
- use_kerning = FT_HAS_KERNING( face );
- previous = 0;
-
- for ( n = 0; n < num_chars; n++ )
- {- /* convert character code to glyph index */
- glyph_index = FT_Get_Char_Index( face, text[n] );
-
- /* retrieve kerning distance and move pen position */
- 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;
- }
-
- /* store current pen position */
- pos[num_glyphs].x = pen_x;
- pos[num_glyphs].y = pen_y;
-
- /* load glyph image into the slot. DO NOT RENDER IT! */
- error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT );
- if ( error ) continue; /* ignore errors, jump to next glyph */
-
- /* extract glyph image and store it in our table */
- error = FT_Get_Glyph( face->glyph, &glyphs[num_glyphs] );
- if ( error ) continue; /* ignore errors, jump to next glyph */
-
- /* increment pen position */
- pen_x += slot->advance.x >> 6;
-
- /* record current glyph index */
- previous = glyph_index;
-
- /* increment number of glyphs */
- num_glyphs++;
- }</pre>
- </font>
-
- <p>As you see, this is a very slight 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 <tt>pen_x</tt> 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;
-
-
- /* initialize string bbox to "empty" values */
- bbox.xMin = bbox.yMin = 32000;
- bbox.xMax = bbox.yMax = -32000;
-
- /* for each glyph image, compute its bounding box, */
- /* translate it, and grow the string bbox */
- 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;
- }
-
- /* check that we really grew the string bbox */
- if ( bbox.xMin > bbox.xMax )
- {- bbox.xMin = 0;
- bbox.yMin = 0;
- bbox.xMax = 0;
- bbox.yMax = 0;
- }
-
- /* return string bbox */
- *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>
- /* compute string dimensions in integer pixels */
- string_width = ( string_bbox.xMax - string_bbox.xMin ) / 64;
- string_height = ( string_bbox.yMax - string_bbox.yMin ) / 64;
-
- /* compute start pen position in 26.6 cartesian pixels */
- 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>Some remarks:</p>
-
- <ul>
- <li>
- The pen position is expressed in the cartesian space (i.e.
- Y upwards).
- </li>
- <li>
- We call <tt>FT_Glyph_To_Bitmap()</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 typecast to an
- <tt>FT_BitmapGlyph</tt>.
- </li>
- <li>
- We use translation when calling <tt>FT_Glyph_To_Bitmap()</tt>.
- This ensures that the <tt>left</tt> and <tt>top</tt> fields of the
- bitmap glyph object are already set to the correct pixel
- coordinates in the cartesian space.
- </li>
- <li>
- 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>.
- </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.</p>
-
- <hr>
-
- <h3>
- 5. Advanced text rendering: transformation + 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 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; /* glyph index */
- FT_Vector pos; /* glyph origin on the baseline */
- FT_Glyph image; /* glyph image */
-
- } 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, which has several
- advantages. Our glyph sequence loader thus becomes:</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;
-
- TGlyph glyphs[MAX_GLYPHS]; /* glyphs table */
- PGlyph glyph; /* current glyph in table */
- FT_UInt num_glyphs;
-
-
- .. initialize library ..
- .. create face object ..
- .. set character size ..
-
- pen_x = 0; /* start at (0,0)! */
- 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;
- }
-
- /* store current pen position */
- 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;
-
- /* translate the glyph image now */
- FT_Glyph_Transform( glyph->image, 0, &glyph->pos );
-
- pen_x += slot->advance.x >> 6;
- previous = glyph->index
-
- /* increment number of glyphs */
- glyph++;
- }
-
- /* count number of glyphs loaded */
- num_glyphs = glyph - glyphs;</pre>
- </font>
-
- <p>Translating glyphs now has several advantages, as mentioned
- earlier. The first one is that we don't need to translate the glyph
- bounding box 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><tt>compute_string_bbox()</tt> can now compute the bounding box of
- a transformed glyph string. For example, we can do something
- like</p>
-
- <font color="blue">
- <pre>
- FT_BBox bbox;
- FT_Matrix matrix;
- FT_Vector delta;
-
-
- ... load glyph sequence
-
- ... setup "matrix" and "delta"
-
- /* transform glyphs */
- for ( n = 0; n < num_glyphs; n++ )
- FT_Glyph_Transform( glyphs[n].image, &matrix, &delta );
-
- /* compute bounding box of transformed glyphs */
- compute_string_bbox( &bbox );</pre>
- </font>
-
- <h4>
- b. Rendering a transformed glyph sequence
- </h4>
-
- <p>However, directly transforming the glyphs in our sequence is not a
- useful idea if we want to reuse them in order to draw the text string
- with various angles or transforms. It is 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;
-
-
- /* get bbox of original glyph sequence */
- compute_string_bbox( &string_bbox );
-
- /* compute string dimensions in integer pixels */
- string_width = ( string_bbox.xMax - string_bbox.xMin ) / 64;
- string_height = ( string_bbox.yMax - string_bbox.yMin ) / 64;
-
- /* set up start position in 26.6 cartesian space */
- start.x = ( ( my_target_width - string_width ) / 2 ) * 64;
- start.y = ( ( my_target_height - string_height ) / 2 ) * 64;
-
- /* set up transformation (a rotation here) */
- matrix.xx = (FT_Fixed)( cos( angle ) * 0x10000L );
- matrix.xy = (FT_Fixed)(-sin( angle ) * 0x10000L );
- matrix.yx = (FT_Fixed)( sin( angle ) * 0x10000L );
- matrix.yy = (FT_Fixed)( cos( angle ) * 0x10000L );
-
- for ( n = 0; n < num_glyphs; n++ )
- {- FT_Glyph image;
- FT_Vector pen;
- FT_BBox bbox;
-
-
- /* create a copy of the original glyph */
- error = FT_Glyph_Copy( glyphs[n].image, &image );
- if ( error ) continue;
-
- /* transform copy (this will also translate it to the */
- /* correct position */
- FT_Glyph_Transform( image, &matrix, &start );
-
- /* check bounding box -- if the transformed glyph image */
- /* is not in our target surface, we can avoid rendering */
- 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;
-
- /* convert glyph image to bitmap (destroy the glyph */
- /* copy!) */
- error = FT_Glyph_To_Bitmap(
- &image,
- ft_render_mode_normal,
- 0, /* no additional translation */
- 1 ); /* destroy copy in "image" */
- 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>There are a few changes compared to the previous version of this
- code:</p>
-
- <ul>
- <li>
- We keep the original glyph images untouched, by transforming a
- copy.
- </li>
- <li>
- We perform clipping computations in order to avoid rendering &
- drawing glyphs that are not within our target surface.
- </li>
- <li>
- 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).
- </li>
- <li>
- 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>.
- </li>
- </ul>
-
- <p>It is possible to call this function several times to render the
- string with different angles, or even change the way <tt>start</tt>
- is computed in order to move it to a 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 consumption. For example, let us assume
- that our text string to render 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 <em>outline</em>, for each glyph in a face. Each outline is defined
- in an abstract grid called the <em>design space</em>, with coordinates
- expressed in nominal <em>font units</em>. 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
- <em>hinting</em> or <em>grid-fitting</em>).</p>
-
- <p>This section 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>to perform "true" WYSIWYG text layout.</p>
- </li>
- <li>
- <p>to access font data 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 transformation whose coefficients are computed with the help
- of the <em>character pixel size</em>:</p>
-
- <font color="purple">
- <pre>
- 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</pre>
- </font>
-
- <p>Here, the value <tt>EM_size</tt> is font-specific and corresponds
- 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>face->units_per_EM</tt>. You should
- check that a font face contains scalable glyph images by using the
- <tt>FT_IS_SCALABLE(face)</tt> macro, which returns true when the font
- is scalable.</p>
-
- <p>When you call the function <tt>FT_Set_Pixel_Sizes()</tt>, you are
- specifying the value of <tt>pixel_size_x</tt> and
- <tt>pixel_size_y</tt>; FreeType will then immediately compute the
- values of <tt>x_scale</tt> and <tt>y_scale</tt>.</p>
-
- <p>When you call the function <tt>FT_Set_Char_Size()</tt>, you are
- 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>face->size->metrics</tt> structure. These fields are:</p>
-
- <center>
- <table width="90%" cellpadding="5">
- <tr valign=top>
- <td>
- <tt>x_ppem</t>
- </td>
- <td>
- 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. <tt>x_ppem</tt> means
- "x pixels per EM".
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>y_ppem</tt>
- </td>
- <td>
- 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. <tt>y_ppem</tt> means
- "y pixels per EM".
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>x_scale</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- <tr valign=top>
- <td>
- <tt>y_scale</tt>
- </td>
- <td>
- 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.
- </td>
- </tr>
- </table>
- </center>
-
- <p>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>
-
- <font color="blue">
- <pre>
- /* convert design distances to 1/64th of pixels */
- pixels_x = FT_MulFix( design_x, face->size->metrics.x_scale );
- pixels_y = FT_MulFix( design_y, face->size->metrics.y_scale );</pre>
- </font>
-
- <p>However, you can also scale the value directly with more accuracy
- by using doubles and the equations:</p>
-
- <font color="blue">
- <pre>
- FT_Size_Metrics* metrics = &face->size->metrics; /* shortcut */
- double pixels_x, pixels_y;
- double em_size, x_scale, y_scale;
-
-
- /* compute floating point scale factors */
- em_size = 1.0 * face->units_per_EM;
- x_scale = metrics->x_ppem / em_size;
- y_scale = metrics->y_ppem / em_size;
-
- /* convert design distances to floating point pixels */
- pixels_x = design_x * x_scale;
- pixels_y = design_y * y_scale;</pre>
- </font>
-
- <h4>
- b. Accessing design metrics (glyph & global)
- </h4>
-
- <p>You can access glyph metrics in font units by specifying the
- <tt>FT_LOAD_NO_SCALE</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 then all be in font units.</p>
-
- <p>Unscaled kerning data can be retrieved using the
- <tt>ft_kerning_mode_unscaled</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
- section 3 of this tutorial part.</p>
-
- <hr>
-
- <h3>
- Conclusion
- </h3>
-
- <p>This is the end of the second part of the FreeType 2 tutorial;
- you are now able to access glyph metrics, manage glyph images, and
- render text much more intelligently (kerning, measuring, transforming
- & caching).</p>
-
- <p>With this knowledge you can 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>