From 1e536983f6ca0a0a684bea5c1d9255232386d293 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 23 Mar 2001 11:20:35 +0000 Subject: [PATCH] removed obsolete documentation files they are now moved to the "www" module, under "www/freetype2/docs" --- docs/cache/cache.txt | 267 ----- docs/convntns.txt | 710 -------------- docs/design/basic-design.png | Bin 2047 -> 0 bytes docs/design/design-1.html | 160 --- docs/design/design-2.html | 187 ---- docs/design/design-3.html | 353 ------- docs/design/design-4.html | 361 ------- docs/design/design-5.html | 458 --------- docs/design/design-6.html | 94 -- docs/design/detailed-design.png | Bin 2462 -> 0 bytes docs/design/index.html | 81 -- docs/design/library-model.png | Bin 4264 -> 0 bytes docs/design/modules.html | 639 ------------ docs/design/simple-model.png | Bin 4045 -> 0 bytes docs/freetype2.html | 352 ------- docs/ft2faq.html | 729 -------------- docs/glyphs/Image1.png | Bin 2926 -> 0 bytes docs/glyphs/Image2.png | Bin 1070 -> 0 bytes docs/glyphs/Image3.png | Bin 3020 -> 0 bytes docs/glyphs/Image4.png | Bin 2526 -> 0 bytes docs/glyphs/bbox1.png | Bin 2888 -> 0 bytes docs/glyphs/bbox2.png | Bin 2722 -> 0 bytes docs/glyphs/body_comparison.png | Bin 2467 -> 0 bytes docs/glyphs/bravo_kerned.png | Bin 1316 -> 0 bytes docs/glyphs/bravo_unkerned.png | Bin 1321 -> 0 bytes docs/glyphs/clipping.png | Bin 3020 -> 0 bytes docs/glyphs/down_flow.png | Bin 2233 -> 0 bytes docs/glyphs/glyphs-1.html | 199 ---- docs/glyphs/glyphs-2.html | 397 -------- docs/glyphs/glyphs-3.html | 430 --------- docs/glyphs/glyphs-4.html | 231 ----- docs/glyphs/glyphs-5.html | 484 ---------- docs/glyphs/glyphs-6.html | 432 --------- docs/glyphs/glyphs-7.html | 356 ------- docs/glyphs/grid_1.png | Bin 2079 -> 0 bytes docs/glyphs/index.html | 200 ---- docs/glyphs/points_conic.png | Bin 846 -> 0 bytes docs/glyphs/points_conic2.png | Bin 1262 -> 0 bytes docs/glyphs/points_cubic.png | Bin 919 -> 0 bytes docs/glyphs/points_segment.png | Bin 661 -> 0 bytes docs/glyphs/twlewis1.png | Bin 1628 -> 0 bytes docs/glyphs/twlewis2.png | Bin 1320 -> 0 bytes docs/glyphs/up_flow.png | Bin 2232 -> 0 bytes docs/image/freetype.jpg | Bin 10516 -> 0 bytes docs/tutorial/metrics.png | Bin 2219 -> 0 bytes docs/tutorial/metrics2.png | Bin 1861 -> 0 bytes docs/tutorial/step1.html | 948 ------------------ docs/tutorial/step2.html | 1607 ------------------------------- 48 files changed, 9675 deletions(-) delete mode 100644 docs/cache/cache.txt delete mode 100644 docs/convntns.txt delete mode 100644 docs/design/basic-design.png delete mode 100644 docs/design/design-1.html delete mode 100644 docs/design/design-2.html delete mode 100644 docs/design/design-3.html delete mode 100644 docs/design/design-4.html delete mode 100644 docs/design/design-5.html delete mode 100644 docs/design/design-6.html delete mode 100644 docs/design/detailed-design.png delete mode 100644 docs/design/index.html delete mode 100644 docs/design/library-model.png delete mode 100644 docs/design/modules.html delete mode 100644 docs/design/simple-model.png delete mode 100644 docs/freetype2.html delete mode 100644 docs/ft2faq.html delete mode 100644 docs/glyphs/Image1.png delete mode 100644 docs/glyphs/Image2.png delete mode 100644 docs/glyphs/Image3.png delete mode 100644 docs/glyphs/Image4.png delete mode 100644 docs/glyphs/bbox1.png delete mode 100644 docs/glyphs/bbox2.png delete mode 100644 docs/glyphs/body_comparison.png delete mode 100644 docs/glyphs/bravo_kerned.png delete mode 100644 docs/glyphs/bravo_unkerned.png delete mode 100644 docs/glyphs/clipping.png delete mode 100644 docs/glyphs/down_flow.png delete mode 100644 docs/glyphs/glyphs-1.html delete mode 100644 docs/glyphs/glyphs-2.html delete mode 100644 docs/glyphs/glyphs-3.html delete mode 100644 docs/glyphs/glyphs-4.html delete mode 100644 docs/glyphs/glyphs-5.html delete mode 100644 docs/glyphs/glyphs-6.html delete mode 100644 docs/glyphs/glyphs-7.html delete mode 100644 docs/glyphs/grid_1.png delete mode 100644 docs/glyphs/index.html delete mode 100644 docs/glyphs/points_conic.png delete mode 100644 docs/glyphs/points_conic2.png delete mode 100644 docs/glyphs/points_cubic.png delete mode 100644 docs/glyphs/points_segment.png delete mode 100644 docs/glyphs/twlewis1.png delete mode 100644 docs/glyphs/twlewis2.png delete mode 100644 docs/glyphs/up_flow.png delete mode 100644 docs/image/freetype.jpg delete mode 100644 docs/tutorial/metrics.png delete mode 100644 docs/tutorial/metrics2.png delete mode 100644 docs/tutorial/step1.html delete mode 100644 docs/tutorial/step2.html diff --git a/docs/cache/cache.txt b/docs/cache/cache.txt deleted file mode 100644 index 4c51948c6..000000000 --- a/docs/cache/cache.txt +++ /dev/null @@ -1,267 +0,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 - 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 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 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 :-) - - - - diff --git a/docs/convntns.txt b/docs/convntns.txt deleted file mode 100644 index 084138325..000000000 --- a/docs/convntns.txt +++ /dev/null @@ -1,710 +0,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 --- diff --git a/docs/design/basic-design.png b/docs/design/basic-design.png deleted file mode 100644 index 5acdccc54ad84ec78d74d3b997451fe288cbe0ad..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2047 zcmZ`)4K&kj8=tgS&zL^^iy8?JHnfnhC}z#f$1}5tgz{NJWRj52B2%F$@)2XKW>caE z%SRiNg-v7`;hCbOFQL?9JUs8yd(Qiw^Pcm&?%(ge?sK1WUFY2Q@5&_L?V*qz5D*9i zb--bWAdn1sHTJESUCksY#x1VWMuM}O-O9?!ssydAE1+Z$=y78)2qahSfU$Lp9sW=v z6T{R~Narh}N1!i1mYq2KSunl)V*cVL6gbqLP`teIa^zis@%K%BIU71ro7UU@8{pg) zUnsmr(5Zt=UI&zcz;Kidgs>)6IN-l|Ej9Z9h-ohv`dpV-g7e!w&~Gu`0_FvFlIR{l zWiJQbh~Wgi$fz=G#ry`&qRV$YAmlt;ZrkG;IH?|Q6_A-G@dQMap~%g#dLm_h#LB_< zC(9*jC#IH2ob=R@T+LPoECQZ~8g^$3=#g4BxoAfsUgAW++gkmLENEqGN8HftUc_;- zNVRXgY#vor5*WciT|V*k@2?2Xb|H)yZ(e(#j~&hQy1sks?S9BpwYiwFL}A}6(0B#c zp{XBCxM~X-v%uYV#zk2l0HAO^Dd>*{BFribZ_bhYe(mwB)_sS0wu@&jKv>L~dT)@h zRf;s-m`DpRbmfH>K$9+YRmO*#c(QG;_WMLnnC}f|;Oy1m(1XltP^ZmBjJt(-amJ^C zYf|GhK`QRI8zuXv#8}A?+zaZr&!t7jMHzM}pb7cf>q2xGW30Zf<0`kdmsUgTt9p8h znz?#bLF}j^FW=&=-nkFdTXw*nU@K3Sx_zoy*aysLu^x%@T}?g!3zdI-$(>SrUIWZ) zx3Ll;w5LywU*#rN?yRJ~QLZMWYlh z9*A2(0NO1=abwyrWkNa|yPh05j;+Z$>PkaW_ZRn28Snaftt$s-kZVsjDa+p#{PEH3 zepOzSW|fa(YB>x%9kz?(c+~rr`0X~p_)lVS$|bEr1-WO-w3`Uh4{-^)HRV*k0lkmf zsEbe#hVhd|{Vij4*;q;ESfF4#44!aL2g)<8Fl=Tkz=$|=O6ra1P5lIKEy&a|AUk$u`d&Up?au@iLp6%>=LTsgcfqC1 zL+K?>vm>;(?KrjjsoVq{Dda41Z^@v+M}G8)DwpaPdUxw?$0tns_76Iw_!rYq zMtEYGiY|h1g#y4KpALnuYy&LEmIag2c*4cmn7D?YBH_k2xr#f^uV!NtnvQ+Swm;uS z%PqH*F2FiR_~(6w)qQVkUTGN6>OdKM%gFE1-1F)~cg}kWM4-cyE)anRxOr0A#Nt7R zGLRkq3?*0wFwdcvZ4Rc(^7J3Zm8sa4so1Y#k8N$?<<~dkppdIUAl||%2fUGFns0@7 zK69#%+k^H)8C{;R=w>1O2@9$I@eRl}Eee&!h``VKIq8^JY_J_XM=vYqkHVko{QThm_#2jXUo3Rg1XD-|kz&`uud}}O z*!tZ{-#Ii5J8f8l+UL!};$1yu9 z7*i?$VNgI6%7EK!P=}e~MUBv8d3vx0Ropi5l2fG;J0z;W|Ad)HwTls264$?FhS}7O zr3d$4^xwN$o61D|^J`%*V~%eiw=4dSU;l0018^ifkT^ zY(zZ1Cxw!?f^QAC?5t@v&$ePtMMIp!5{$$pF}%IoCnaJa)r{dE80^GvMj=s9~zJ4^k*0tF^FBDfL z2X0Cymy?>ZAGGG11Zvb1?ooTrk>$ImMNDr2d?;TaGG#@~C+wc6K_6=xx-Urx)NgzF zMV)uyRR2oNAeW lhi7G&7 - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
-   - - Contents - - Next -
-
- -

- - - -
-

- Introduction -

-
- -

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.

- -

Before anything else, it is important to understand the - purpose of this library, i.e., why it has been written:

- -
    -
  • -

    It allows client applications to access font files easily, - wherever they could be stored, and as independently of the font format - as possible.

    -
    • -
  • -

    Easy retrieval of global font data most commonly found in - normal font formats (i.e. global metrics, encoding/charmaps, - etc.).

    -
    • -
  • -

    It allows easy retrieval of individual glyph data - (metrics, images, name, anything else).

    -
    • -
  • -

    Access to font format-specific "features" whenever - possible (e.g. SFNT tables, Multiple Masters, OpenType Layout tables, - etc.).

    -
    • -
- -

Its design has also severely been influenced by the following - requirements:

- -
    -
  • -

    High portability. 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.

    -
    • -
  • -

    Extendability. 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.

    -
    • -
  • -

    Customization. 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.

    -
    • -
  • -

    Compactness and efficiency. The primary target - for this library are embedded systems with low cpu and memory - resources.

    -
    • -
- -

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.

- -

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.

- -

- -
- - - - - - -
-   - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/design/design-2.html b/docs/design/design-2.html deleted file mode 100644 index 39a9ac86a..000000000 --- a/docs/design/design-2.html +++ /dev/null @@ -1,187 +0,0 @@ - - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- I. Components and APIs -

-
- -

It's better to describe FreeType 2 as a collection of - components. 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.

- -

A first brief description of this system of components could be:

- -
    -
  • -

    Client applications typically call the FreeType 2 - high-level API, whose functions are implemented in a single - component called the Base Layer.

    -
    • -
  • -

    Depending on the context or the task, the base layer then calls one - or more module components to perform the work. In most - cases, the client application doesn't need to know which module was - called.

    -
    • -
  • -

    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 - low-level base API.

    -
    • -
- -

This is illustrated by the following graphics (note that component - entry points are represented as colored triangles):

- -
- Basic FreeType design -
- -

Now, a few additional things must be added to complete this - picture:

- -
    -
  • -

    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 ftsystem component, which is in - charge of implementing memory management & input stream access, as - well as ftinit, which is in charge of library initialization - (i.e. implementing the FT_Init_FreeType() function).

    -
    • -
  • -

    FreeType 2 comes also with a set of optional - components, which can be used either as a convenience for client - applications (e.g. the ftglyph 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 - ftmm component used to access and manage Multiple Masters - data in Type 1 fonts).

    -
    • -
  • -

    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 truetype and - cff modules both use the routines provided by the - sfnt module).

    -
    • -
- -

Hence, a more complete picture would be:

- -
- Detailed FreeType design -
- -

Please take note of the following important points:

- -
    -
  • -

    An optional component can use either the high-level or base API. - This is the case of ftglyph in the above picture.

    -
    • -
  • -

    Some optional components can use module-specific interfaces ignored - by the base layer. In the above example, ftmm directly - accesses the Type 1 module to set/query data.

    -
    • -
  • -

    A replacable component can provide a function of the high-level - API. For example, ftinit provides - FT_Init_FreeType() to client applications.

    -
    • -
- -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/design/design-3.html b/docs/design/design-3.html deleted file mode 100644 index 947fccedb..000000000 --- a/docs/design/design-3.html +++ /dev/null @@ -1,353 +0,0 @@ - - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- II. Public Objects and Classes -

-
- -

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.

- -

- 1. Object Orientation in FreeType 2 -

- -

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:

- -
    -
  1. -

    Each object type/class has a corresponding structure - type and a corresponding structure pointer - type. The latter is called the handle type for the - type/class.

    - -

    Consider that we need to manage objects of type "foo" in - FreeType 2. We would define the following structure and handle - types as follows:

    - - 
    -    typedef struct FT_FooRec_*  FT_Foo;
-
-    typedef struct  FT_FooRec_
-    {
-      // fields for the "foo" class
-      ...
-
-    } FT_FooRec;
    -     - -

    As a convention, handle types use simple but meaningful - identifiers beginning with FT_, as in FT_Foo, - while structures use the same name with a Rec suffix - appended to it ("Rec" is short for "record"). Note that each - class type has a corresponding handle type.

    -
    2. -
  2. -

    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:

    - - 
    -    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;
    -     - -

    As you can see, we ensure that a "foobar" object is also a "foo" - object by placing a FT_FooRec at the start of the - FT_FooBarRec definition. It is called root by - convention.

    - -

    Note that a FT_FooBar handle also points to a "foo" - object and can be typecasted to FT_Foo. Similarly, when - the library returns a FT_Foo handle to client applications, - the object can be really implemented as a FT_FooBar or any - derived class from "foo".

    -
    3. -
- -

In the following sections of this chapter, we will refer to "the - FT_Foo class" to indicate the type of objects handled through - FT_Foo pointers, be they implemented as "foo" or "foobar".

- -
- -

- 2. The FT_Library class -

- -

This type corresponds to a handle to a single instance of the - library. Note that the corresponding structure FT_LibraryRec - is not defined in public header files, making client applications unable - to access its internal fields.

- -

The library object is the parent 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).

- -

Typical client applications should call FT_Init_FreeType() - in order to create a new library object, ready to be used for further - actions.

- -

Another alternative is to create a fresh new library instance by - calling the function FT_New_Library(), defined in the - <freetype/ftmodule.h> 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 - FT_Add_Module() manually.

- -

Calling FT_Init_FreeType() 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 - ftinit component. This process is explained in details later - in this document.

- -

For now, one should consider that library objects are created with - FT_Init_FreeType(), and destroyed along with all children with - FT_Done_FreeType().

- -
- -

- 3. The FT_Face class -

- -

A face object corresponds to a single font face, i.e., a - specific typeface with a specific style. For example, "Arial" and - "Arial Italic" correspond to two distinct faces.

- -

A face object is normally created through FT_New_Face(). - This function takes the following parameters: an FT_Library - 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 - FT_Face handle. It returns an error code:

- - 
-    FT_Error  FT_New_Face( FT_Library   library,
-                           const char*  filepathname,
-                           FT_Long      face_index,
-                           FT_Face*     face );
- - -

In case of success, the function will return 0, and the handle - pointed to by the face parameter will be set to a non-NULL - value.

- -

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 FT_FaceRec definition in the - FreeType 2 API Reference.

- -
- -

- 4. The FT_Size class -

- -

Each FT_Face object has one or more - FT_Size objects. A size object 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 - face->size.

- -

The contents of a size object can be changed by calling either - FT_Set_Pixel_Sizes() or FT_Set_Char_Size().

- -

A new size object can be created with FT_New_Size(), and - destroyed manually with FT_Done_Size(). Note that typical - applications don't need to do this normally: they tend to use the - default size object provided with each FT_Face.

- -

The public fields of FT_Size objects are defined in a very - small structure named FT_SizeRec. However, it is important to - understand that some font drivers define their own derivatives of - FT_Size to store important internal data that is re-computed - each time the character size changes. Most of the time, these are - size-specific font hints./p> - -

For example, the TrueType driver stores the scaled CVT table that - results from the execution of the "cvt" program in a TT_Size - structure, while the Type 1 driver stores scaled global metrics - (like blue zones) in a T1_Size 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 :-)

- -
- -

- 5. The FT_GlyphSlot class -

- -

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).

- -

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.

- -

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.

- -

The base FT_GlyphSlotRec structure only presents glyph - metrics and images to client applications, while actual implementation - may contain more sophisticated data.

- -

As an example, the TrueType-specific TT_GlyphSlotRec - 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 T1_GlyphSlotRec 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.

- -

Finally, each face object has a single glyph slot that is directly - accessible as face->glyph.

- -
- -

- 6. The FT_CharMap class -

- -

The FT_CharMap type is used as a handle to character map - objects, or charmaps. 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.

- -

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.

- -

Each FT_CharMap object contains a "platform" and an - "encoding" field used to identify precisely the character repertoire - corresponding to it.

- -

Each font format provides its own derivative of - FT_CharMapRec and thus needs to implement these objects.

- -
- -

- 7. Objects relationships -

- -

The following diagram summarizes what we have just said regarding the - public objects managed by the library, as well as explicitely describes - their relationships

- -
- Simple library model -
- -

Note that this picture will be updated at the end of the next - chapter, related to internal objects.

- -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/design/design-4.html b/docs/design/design-4.html deleted file mode 100644 index 6bdfbb56f..000000000 --- a/docs/design/design-4.html +++ /dev/null @@ -1,361 +0,0 @@ - - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- III. Internal Objects and Classes -

-
- -

Let us have a look now at the internal objects that - FreeType 2 uses, i.e., those not directly available to client - applications, and see how they fit into the picture.

- -

- 1. Memory management -

- -

All memory management operations are performed through three specific - routines of the base layer, namely: FT_Alloc(), - FT_Realloc(), and FT_Free(). Each one of these - functions expects a FT_Memory handle as its first - parameter.

- -

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 FT_Init_FreeType(), calling the function - FT_New_Memory() provided by the ftsystem - component.

- -

By default, this manager uses the ANSI malloc(), - realloc(), and free() functions. However, as - ftsystem is a replaceable part of the base layer, a specific - build of the library could provide a different default memory - manager.

- -

Even with a default build, client applications are still able to - provide their own memory manager by not calling - FT_Init_FreeType() but follow these simple steps:

- -
    -
  1. -

    Create a new FT_Memory object by hand. The definition - of FT_MemoryRec is located in the public file - <freetype/ftsystem.h>.

    -
    2. -
  2. -

    Call FT_New_Library() to create a new library instance - using your custom memory manager. This new library doesn't yet - contain any registered modules.

    -
    3. -
  3. -

    Register the set of default modules by calling the function - FT_Add_Default_Modules() provided by the ftinit - component, or manually register your drivers by repeatedly - calling FT_Add_Module().

    -
    4. -
- -
- -

- 2. Input streams -

- -

Font files are always read through FT_Stream objects. The - definition of FT_StreamRec is located in the public file - <freetype/ftsystem.h>, which allows client developers to - provide their own implementation of streams if they wish so.

- -

The function FT_New_Face() will always automatically create - a new stream object from the C pathname given as its second - argument. This is achieved by calling the function - FT_New_Stream() provided by the ftsystem component. - As the latter is replaceable, the implementation of streams may vary - greatly between platforms.

- -

As an example, the default implementation of streams is located in - the file src/base/ftsystem.c and uses the ANSI - fopen(), fseek(), and fread() 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.

- -

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 - frames, and temporarily buffered similarly through typical - seek/read operations.

- -

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".

- -

The function FT_New_Memory_Face() can be used to directly - create/open a FT_Face object from data that is readily - available in memory (including ROM-based fonts).

- -

Finally, in the case where a custom input stream is needed, client - applications can use the function FT_Open_Face(), 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.

- -

Note that each face owns a single stream, which is also destroyed by - FT_Done_Face(). Generally speaking, it is certainly - not a good idea to keep numerous FT_Face objects - opened.

- -
- -

- 3. Modules -

- -

A FreeType 2 module is itself a piece of code. However, the - library creates a single FT_Module object for each module that - is registered when FT_Add_Module() is called.

- -

The definition of FT_ModuleRec is not publicly available to - client applications. However, each module type is described by - a simple public structure named FT_Module_Class, defined in - <freetype/ftmodule.h>, and is described later in this - document:

- -

You need a pointer to an FT_Module_Class structure when - calling FT_Add_Module(), whose declaration is:

- - 
-    FT_Error  FT_Add_Module( FT_Library              library,
-                             const FT_Module_Class*  clazz );
- - -

Calling this function will do the following:

- -
    -
  • -

    It will check whether the library already holds a module object - corresponding to the same module name as the one found in - FT_Module_Class.

    -
    • -
  • -

    If this is the case, it will compare the module version number to - see whether it is possible to upgrade 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.

    -
    • -
  • -

    It creates a new FT_Module object, using data and flags - of the module class to determine its byte size and how to properly - initialize it.

    -
    • -
  • -

    If a module initializer is present in the module class, it will - be called to complete the module object's initialization.

    -
    • -
  • -

    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.

    -
    • -
- -

Note that this function doesn't return an FT_Module handle, - given that module objects are completely internal to the library (and - client applications shouldn't normally mess with them :-)

- -

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:

- -
    -
  • -

    Renderer 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.

    -
    • -
  • -

    Font driver modules are used to support one or more font - formats. Typically, each font driver provides a specific - implementation/derivative of FT_Face, FT_Size, - FT_GlyphSlot, as well as FT_CharMap.

    -
    • -
  • -

    Helper modules are shared by several font drivers. For - example, the sfnt module parses and manages tables found in - SFNT-based font formats; it is then used by both the TrueType and - OpenType font drivers.

    -
    • -
  • -

    Finally, the auto-hinter 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.

    -
    • -
- -

Note that every FT_Face object is owned 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 - FT_Remove_Module() function).

- -

Because of this, you should always take care that no - FT_Face object is opened when you upgrade or remove a module - from a library, as this could cause unexpected object deletion!

- -
- -

- 4. Libraries -

- -

We now come back to our well-known FT_Library object. From - what have been said before, we already know that a library instance owns - at least the following:

- -
    -
  • -

    A memory manager object (FT_Memory), used for all - allocation/releases within the instance.

    -
    • -
  • -

    A list of FT_Module objects, corresponding to the - "installed" or "registered" modules of the instance. This list can - be changed at any time through FT_Add_Module() and - FT_Remove_Module().

    -
    • -
  • -

    Remember that face objects are owner by font drivers that are - themselves modules owned by the library.

    -
    • -
- -

There is however another object owned by the library instance that - hasn't been described yet: the raster pool.

- -

The raster pool 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 :-).

- -

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).

- -

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.

- -

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).

- -
- -

- 5. Summary -

- -

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:

- -
- Complete library model -
- -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/design/design-5.html b/docs/design/design-5.html deleted file mode 100644 index 71fa25db0..000000000 --- a/docs/design/design-5.html +++ /dev/null @@ -1,458 +0,0 @@ - - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- IV. Module Classes -

-
- -

We will now try to explain more precisely the types 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.

- -
    -
  • -

    Renderer modules are used to manage scalable glyph images. - This means transforming them, computing their bounding - box, and converting them to either monochrome - or anti-aliased bitmaps.

    - -

    Note that FreeType 2 is capable of dealing with any - kind of glyph images, as long as a renderer module is provided for it. - The library comes by default with two renderers:

    - -

    - - - - - - - - -
    - raster - -

    Supports the conversion of vectorial outlines (described by a - FT_Outline object) to monochrome bitmaps. -

    - smooth - -

    Supports the conversion of the same outlines to high-quality - anti-aliased pixmaps (using 256 levels of gray). Note - that this renderer also supports direct span generation.

    -

    - -
  • -

    Font driver modules are used to support one or more - specific font format. By default, FreeType 2 comes with the - following font drivers:

    - -

    - - - - - - - - - - - - - - - - - - - - -
    - truetype - -

    supports TrueType font files

    -
    - type1 - -

    supports Postscript Type 1 fonts, both in binary - (.pfb) or ASCII (.pfa) formats, including - Multiple Master fonts.

    -
    - cid - -

    supports Postscript CID-keyed fonts

    -
    - cff - -

    supports OpenType, CFF as well as CEF fonts (CEF is a - derivative of CFF used by Adobe in its SVG viewer)

    -
    - winfonts - -

    supports Windows bitmap fonts (i.e. .fon and - .fnt)

    -

    - -

    Note that font drivers can support bitmapped or scalable glyph - images. A given font driver that supports Bézier outlines - through FT_Outline can also provide its own hinter, or rely - on FreeType's autohinter module.

    -
    • - -
  • -

    Helper modules are used to hold shared code that is often - used by several font drivers, or even other modules. Here are the - default helpers:

    - -

    - - - - - - - - - - - - -
    - sfnt - - used to support font formats based on the SFNT storage - scheme: TrueType & OpenType fonts as well as other variants (like - TrueType fonts that only contain embedded bitmaps) -
    - psnames - - 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. -
    - psaux - - used to provide various useful functions related to Type 1 - charstring decoding, as this "feature" is needed by the - type1, cid, and cff drivers. -

    -
    • - -
  • -

    Finally, the autohinter 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.

    - -

    This module's purpose and design is also heavily described on the - FreeType web site.

    -
    • -
- -

We will now study how modules are described, then managed by the - library.

- -

- 1. The FT_Module_Class structure -

- -

As described later in this document, library initialization is - performed by calling the FT_Init_FreeType() function. The - latter is in charge of creating a new "empty" FT_Library - object, then register each "default" module by repeatedly calling the - FT_Add_Module() function.

- -

Similarly, client applications can call FT_Add_Module() any - time they wish in order to register a new module in the library. Let us - take a look at this function's declaration:

- - 
-    extern FT_Error  FT_Add_Module(
-                       FT_Library              library,
-                       const FT_Module_Class*  clazz );
- - -

As one can see, this function expects a handle to a library object, - as well as a pointer to a FT_Module_Class 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!

- -

Here the definition of FT_Module_Class, with some - explanation. The following code is taken from - <freetype/ftmodule.h>:

- - 
-    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;
- - -

A description of its fields:

- -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- module_flags - -

A set of bit flags used to describe the module's category. Valid - values are:

- -
    -
  • - ft_module_font_driver if the module is a font driver -
    • -
  • - ft_module_renderer if the module is a renderer -
    • -
  • - ft_module_hinter if the module is an auto-hinter -
    • -
  • - ft_module_driver_scalable if the module is a font - driver supporting scalable glyph formats -
    • -
  • - ft_module_driver_no_outlines if the module is a font - driver supporting scalable glyph formats that cannot be - described by an FT_Outline object -
    • -
  • - ft_module_driver_has_hinter if the module is a font - driver that provides its own hinting scheme/algorithm -
    • -
-
- module_size - -

An integer that gives the size in bytes of a given - module object. This should never be less than - sizeof(FT_ModuleRec), but can be more if the module needs - to sub-class the base FT_ModuleRec class.

-
- module_name - -

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 FT_Library object. However, - FT_Add_Module() uses the module_version field to - detect module upgrades and perform them cleanly, even at - run-time.

-
- module_version - -

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 FT_Add_Module().

-
- module_requires - -

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

-
- module_requires - -

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.

- -

Note that is is optional, and can be set to NULL. Other - interfaces can also be accessed through the get_interface() - field.

-
- module_init - -

A pointer to a function used to initialize the fields of a fresh - new FT_Module object. It is called after the - module's base fields have been set by the library, and is generally - used to initialize the fields of FT_ModuleRec - subclasses.

- -

Most module classes set it to NULL to indicate that no extra - initialization is necessary.

-
- module_done - -

A pointer to a function used to finalize the fields of a given - FT_Module object. Note that it is called before - the library unsets the module's base fields, and is generally used - to finalize the fields of FT_ModuleRec subclasses.

- -

Most module classes set it to NULL to indicate that no extra - finalization is necessary

-
- get_interface - -

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.

-

- - -

- 2. The FT_Module type -

- -

The FT_Module type is a handle (i.e. a pointer) to a given - module object/instance, whose base structure is given by the internal - FT_ModuleRec type. We will intentionally not describe - this structure here, as there is no point to look so far into the - library's design.

- -

When FT_Add_Module is called, it first allocates a new - module instance, using the module_size class field to determine - its byte size. The function initializes the root FT_ModuleRec - field, then calls the class-specific initializer module_init - when this field is not set to NULL.

- -

Note that the library defines several sub-classes of - FT_ModuleRec, which are, as you could have guessed:

- -
    -

  • FT_Renderer for renderer modules

    -

  • FT_Driver for font driver modules

    -

  • FT_AutoHinter for the auto-hinter

    -
- -

Helper modules use the base FT_ModuleRec type. We will - describe these classes in the next chapters.

- -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/design/design-6.html b/docs/design/design-6.html deleted file mode 100644 index f7c0a9e1d..000000000 --- a/docs/design/design-6.html +++ /dev/null @@ -1,94 +0,0 @@ - - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - -   -
-
- -

- - - -
-

- TO BE CONTINUED... -

-
- - -

- -
- - - - - - -
- Previous - - Contents - -   -
-
- -
-
- - - diff --git a/docs/design/detailed-design.png b/docs/design/detailed-design.png deleted file mode 100644 index d27f761a1858a08b1aafddd5757f90c96f2d02c4..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2462 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 G_QCIzy?>zq diff --git a/docs/design/index.html b/docs/design/index.html deleted file mode 100644 index 0270fa8b7..000000000 --- a/docs/design/index.html +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - The design of FreeType 2 - - - - -

- The design of FreeType 2 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- - -
- - -
- -

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.

- - - - - -
-

- Table of Contents -

-
- -
- - -
- -

- Introduction -

- -

- I. Components and APIs -

- -

- II. Public Objects and Classes -

- -

- III. Internal Objects and Classes -

- -

- IV. Module Classes -

- -
-
- -
-
- - diff --git a/docs/design/library-model.png b/docs/design/library-model.png deleted file mode 100644 index b305458c23eacc2abfb496debac4e8449443ec73..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4264 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 diff --git a/docs/design/modules.html b/docs/design/modules.html deleted file mode 100644 index fad6e6233..000000000 --- a/docs/design/modules.html +++ /dev/null @@ -1,639 +0,0 @@ - -FreeType 2 - Modules - - - - - -
- -

FreeType 2 Modules

- -
-

Introduction

-
- -

-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:

- -
    -

  • - what is a module, and what kind of modules are recognized - by the library? -

    • - -

  • - how are modules registered and managed by the library? -

    • - -

  • - how to write a new module, especially new font drivers? -

    • - -

  • - how to select specific modules for a given build of the - library ? -

    • - -

  • - how to compile modules as stand-alone DLLs / shared objects? -

    • - -
- -
-

Overview

-
- - -

1. Library design:

- -

The design of the library is pretty basic:

-
    -

  • - client applications typically call the FreeType 2 high-level - API, whose functions are implemented in a single component - called the Base Layer. -

    • - -

  • - 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. -

    • - -

  • - 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". -

    • -
- -

This is illustrated by the following graphics:

- -
- -

Note that, however, FT2 comes with a set of optional -components that can be ommited from certain builds, and whose -purpose vary between two situations:

- -
    -

  • - 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.

    - -

    As an example, see the the ftglyph component - that is used to manipulate glyph images more conveniently - than the default API.

    -

    • - -

  • - some other components complement the base layer, by providing - additional routines. Most of them allow client applications - to access format-specific data.

    - -

    For example, the ftmm component provides high-level - functions to specify Multiple Master coordinates for MM Type 1 - fonts.

    -

    • -
- -

This is illustrated by the following graphics:

- -
- -
-

Module Classes

-
- -

-The library is capable of managing and using several kinds of -modules:

- -
    -

  • - renderer modules are used to convert scalable glyph images - to bitmaps. FreeType 2 comes by default with two of them:

    - -
    -

    raster1

    -     		-

    supports the conversion of vectorial outlines (described by a - FT_Outline object) to monochrome bitmaps. -

    - -

    smooth

    -     		-

    supports the conversion of the same outlines to high-quality - anti-aliased pixmaps.

    -
    - - -

    The specification and interface of renderers is described in - details within this document.

    - -

    Note that most font formats use FT_Outline 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 :-). -

    • - -

  • - font driver modules are used to support one or more specific - font format. By default, FT2 comes with the following modules:

    - -
    - -
    -

    truetype

    -     		-

    supports TrueType font files

    -
    - -

    type1

    -     		-

    supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII - (.pfa) formats, including Multiple Master fonts.

    -
    - -

    cid

    -     		-

    supports Postscript CID-keyed fonts

    -
    - -

    cff

    -     		-

    supports OpenType, CFF as well as CEF fonts (CEF is a derivative - of CFF used by Adobe in its SVG viewer).

    -
    - -

    winfonts

    -     		-

    supports Windows bitmap fonts (i.e. ".FON" and ".FNT").

    -
    - -

    Note that font drivers can support bitmapped or scalable glyph - images. A given font driver that supports bezier outlines through - the FT_Outline can also provide its own hinter, or rely - on FreeType's autohinter module. -

    • - -

  • - helper 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:

    - -
    - sfnt - - used to support font formats based on the "SFNT" - storage scheme. This means TrueType & OpenType fonts as - well as other variants (like TrueType fonts that only - contain embedded bitmaps). -
    - - psnames - - 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. -
    -

    • - - -

  • - finally, the autohinter 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. -

    • -
- -

We will now study how modules are described, then managed by - the library.

- -

1. The FT_Module_Class structure:

- -

As described later in this document, library initialisation is - performed by calling the FT_Init_FreeType function. The - latter is in charge of creating a new "empty" FT_Library - object, then register each "default" module by repeatedly calling - the FT_Add_Module function.

- -

Similarly, client applications can call FT_Add_Module - any time they wish in order to register a new module in the library. - Let's take a look at this function's declaration:

- -

-    extern FT_Error  FT_Add_Module( FT_Library              library,
-                                    const FT_Module_Class*  clazz );
-
- -

As one can see, this function expects a handle to a library object, - as well as a pointer to a FT_Module_Class 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 !.

- -

Let's study the definition of FT_Module_Class, and explain it - a bit. The following code is taken from - <freetype/ftmodule.h>:

- -

-  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;
-
- -

here's a description of its fields:

- -
-

module_flags

-		 -

this is a set of bit flags used to describe the module's -category. Valid values are:

-
    -

  • - ft_module_font_driver if the module is a font driver -

    • - -

  • - ft_module_renderer if the module is a renderer -

    • - -

  • - ft_module_hinter if the module is an auto-hinter -

    • - -

  • - ft_module_driver_scalable if the module is a font - driver supporting scalable glyph formats. -

    • - -

  • - ft_module_driver_no_outlines if the module is a - font driver supporting scalable glyph formats that cannot - be described by a FT_Outline object -

    • - -

  • - ft_module_driver_has_hinter if the module is a font - driver that provides its own hinting scheme/algorithm -

    • -
-
- -

module_size

-		 -

an integer that gives the size in bytes of a given module -object. This should never be less than -sizeof(FT_ModuleRec), but can be more when the module -needs to sub-class the base FT_ModuleRec class.

-
- -

module_name

-		 -

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 FT_Library object. However, FT_Add_Module -uses the module_version field to detect module upgrades -and perform them cleanly, even at run-time.

-
- -

module_version

-		 -

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 FT_Add_Module.

-
- -

module_requires

-		 -

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

-
- -

module_requires

-		 -

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.

- -

Note that is is optional, and can be set to NULL. Other interfaces -can also be accessed through the get_interface field.

-
- -

module_init

-		 -

this is a pointer to a function used to initialise the fields of -a fresh new FT_Module object. It is called after the module's -base fields have been set by the library, and is generally used to -initialise the fields of FT_ModuleRec subclasses.

- -

Most module classes set it to NULL to indicate that no extra -initialisation is necessary

-
- -

module_done

-		 -

this is a pointer to a function used to finalise the fields of -a given FT_Module object. Note that it is called before the -library unsets the module's base fields, and is generally used to -finalize the fields of FT_ModuleRec subclasses.

- -

Most module classes set it to NULL to indicate that no extra -finalisation is necessary

-
- -

get_interface

-		 -

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.

-
- -
- - -

2. The FT_Module type:

- -

the FT_Module type is a handle (i.e. a pointer) to a given - module object / instance, whose base structure is given by the - internal FT_ModuleRec type (we will not detail its - structure here).

- -

When FT_Add_Module is called, it first allocate a new - module instance, using the module_size class - field to determine its byte size. The function initializes - a the root FT_ModuleRec fields, then calls - the class-specific initializer module_init - when this field is not set to NULL.

- - - - -
-

Renderer Modules

-
- -

As said previously, renderers are used to convert scalable - glyph images to bitmaps or pixmaps. Each renderer module is defined - through a renderer class, whose definition is found in the - file <freetype/ftrender.h>. However, a few concepts - need to be explained before having a detailed look at this structure. -

- -

1. Glyph formats:

- -

Each glyph image that is loaded by FreeType (either through - FT_Load_Glyph or FT_Load_Char), has a given - image format, described by the field - face->glyph->format. It is a 32-byte integer that - can take any value. However, the file <freetype/ftimage.h> - defines at least the following values:

- -
- - - - - - - - -
-ft_glyph_format_bitmap - -this value is used to indicate that the glyph image is a bitmap or pixmap. -Its content can then be accessed directly from -face->glyph->bitmap after the glyph was loaded. -
-ft_glyph_format_outline - -this value is used to indicate that the glyph image is a scalable vectorial -outline, that can be described by a FT_Outline object. Its content -can be accessed directly from -face->glyph->outline after the glyph was loaded. -this is the format that is commonly returned by TrueType, Type1 and -OpenType / CFF fonts. -
-ft_glyph_format_plotter - -this value is equivalent to ft_glyph_format_outline 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). -
-ft_glyph_format_composite - -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 FT_LOAD_NO_RECURSE flag. The list of -subglyphs that make up the composite can be accessed directly as -face->glyph->subglyphs after the glyph was loaded. -
- -

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 face->glyph->other.

- -

2. The FT_Outline type:

- -

This structure, which is also defined, and heavily commented, in - the file <freetype/ftimage.h>, 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.

- -

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.

- -

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:

- -

    -
  • raster1, used to convert them to monochrome bitmaps
    • -
  • smooth, used to convert them to high-quality anti-aliased - pixmaps
    • -

- -

3. Bitmaps and scan-conversion:

- -

Bitmaps and pixmaps are described through a FT_Bitmap - structure, which is defined and heavily commented in - <freetype/ftimage.h> - - -


-  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 Driver Modules

-
- -
-

Library Initialisation & Dynamic Builds

-
- -

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

- -

Such applications must normally call the FT_Init_FreeType - function before using the library. This function is in charge of - two things:

- -
    -

  • - First, it creates a FT_Library object (by calling - the public function FT_New_Library). This new - object is "empty" and has no module registered in it. -

    • - -

  • - Then, it registers all "default modules" by repeatedly calling - FT_Add_Module. -

    • -
- -

It is important to notice that the default implementation of - FT_Init_FreeType, which is located in the source - file "src/base/ftinit.c" always uses a static - list of modules that is generated at compile time from the - configuration file <freetype/config/ftmodule.h>. -

- -

There are cases where this may be inadequate. For example, one - might want to compile modules as independent DLLs in a specific - location (like "/usr/lib/freetype/module/"), and have - the library initialisation function load the modules dynamically - by parsing the directory's content

- -

This is possible, and we're going to explain how to do it.

- - -

a. Building the library as a DLL (i.e. "shared object" on Unix)

- -

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.

- -

When building dynamic libraries, certain compilers require specific - directives to declare exported DLL entry points. For example, the - "__cdecl" 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).

- -

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.

- -

To allow such compilations, the FT_EXPORT_DEF() 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 - <freetype/freetype.h>:

- -

-   FT_EXPORT_DEF(FT_Error)  FT_Init_FreeType( void );
-
- -

the definition of FT_EXPORT_DEF(x) defaults to "extern x", - except when a specific definition is given in the library's system-specific - configuration file <freetype/config/ftconfig.h>. This - allows project builders to specify the exact compilation directive - they need.

- -

Similarly, the FT_EXPORT_FUNC(x) macro is defined and used to - define exported functions within the FreeType 2 source code. - However, it is only used at compilation time.

- - -

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).

- - -

b. Building modules as DLLs

- -

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.

- -

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 - BASE_DEF(x) macro. The latter is similar to - FT_EXPORT_DEF and defaults to "extern x" unless - you specify a specific definition in - <freetype/config/ftconfig.h>.

-

- -

- -
-

Conclusion

-
- -
- - diff --git a/docs/design/simple-model.png b/docs/design/simple-model.png deleted file mode 100644 index 25434044e3795d58d9e310420239aa1f1584a6f9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4045 zcmd5?o{2GA5-^KeRaNi->*)c?_Hkf zeUfafkutlKb^!n&V}1#K1pp-8idQ&jyV&CCeDSFGC5<&TzX}pRIMD4x0FaF{hhMlF zn#W~2`qC|wVr*Ab&wp_Ai`YNr_aV&9gh8}^GHnB=YCx)(JSEyTcRa^ zifG5&4z1!f&8D<)V0o5-`*^=v#=B`{OgBP^AmfFqc8-+Yyc^ z-?>b3TWG<2k$?w!-@RulOr>@+(07%pqk+3KDl#}d zP1WO@=>|mQuEomeFauR#$J*D&Hc1$8BQtKVh^-F>|e zp6y@-PUtrPoACztB0|Nlw0(ZiOO>0egK~5O*>K{nmixUPBTr^$%t0ccs#?^N2d2v{v9&8zrlyS-gf9MGQf9j`qMCeiC2sb8tUwY zl?KtVb-6DNsI`loE0?@nKS_G!sv==VI`=>>MjH5%62WEXJ(~OAf>Hsj53%qiH0cN+ zKI!FSCtaTo`vDF}@UFf0ngFJJ{@xIbI;)QqXTT=Mi6nTVY$1+0%w@zNoM5U?@4<$a zsXsvf@2%qIrkCZ9yF5Lv9gkGGFPNR>6DsoNq^1rStGT~bmastiE{knYRPd=UjXWL# zP$|xakykd>z6n|Vv*#~cJ+jt?-)67dWtjWv>Q*$&6*RV%c=S5Q*9yZdjyf4<(_b&x zkljdvaFKG|s&K`Fy^5teHj4C4bo4Jt-|?QX>#eKX&0f->-azeCZBxeMXYy9+YDzv{ z_tt=TWn$W^J>XgUs0@$ngNlP`w=z9zKy&Id42qLkm?c#aMGbCxHut1jr-C6rUC{fS z2s3Rcr3+W{KMopD70s{>(B2}#Ync30__Z?Q{P7GA+}IWPd~ov<%$qMh-eZ`oTfPyh z+)Ky=vt*kBReNH)T?!P2x5-+tCrY+C{sAoQ2(ta-J@oytr~iPQxa7;JySScG9`b)+ zk%9#>*(}LMDMk_eJg)Kkd0G6QN0Dovi5KqomNZ_MhoSYDOr5%&ViZQc4a z#thH?jwKt6GrXOFK07OLdgk^{aX)TPPjU0sFt#H|eP|IEbKS+?#`sd_g{4U|gQH}S zzme^UhkzubsBy4a;_q>hJYOG~OF}gPPr+2Pl_Z1A(0y$=ow=!M8_~0|iQl3bfaZ{PTV( z(t{jrWw~xN&`-XP;D|&50WCDQc0)Prbj&SBauz#r3-xt1a%=}?Ar&L`rO$(CqxhL0UVS@HY0SOOZYNZ>_qmZ}3? zEPESt-e+y~*0MWY@>s%rx_*kWtii5@Q;%gyL`S{Nn z`4@N=(^Ssk-IUgt3Txm0R}wUIkkP_mdq?@AnXmlFt##Z+X*_EuR}SHOM*8Wh0IM9U#ySCwJ|&QH?zT>lYo^K_;AjA(<&i3uWsj(5J`rs01Zz)=|q zUtR~m~V{Y6>#sjCqC;ZRaeg@yw@>bXK zNzpVqMmENcVH1lIRTFwPPMB!9LOeoGCP9(%h~T?x7ttjNdKj?nXHC;fNpCV}@C+Z* zOPZYlm$mMzk-9asP7G3!!yj)9()M!T2xE>yb#{M+tmCBPL;)P&eA)L0I$s0 z0DhNvvm20K^)39!CU)TBp^?0Se9M$-t zWir=%v1(k!cDLQZVavmD=!4NcxbU#j8kU+%lDh%C>bz<9^%B2vfdzzf48Lt9VfFIt zM^aa7)E?Gz0&L>9Lozil;yd)~TDHs3Yn_-ans{9~)6SoxG71?T`knm^c`R2>|25m@ zL^;U{2N7L46+DL69jjj38F0Pt=d6(9;$Y9j{$P68;bnl&W0(pY)Nqew-}I(xH>v)< zoFo#f*F}S`$P|>djd|ygQvQZB(EPzQ~wT7fa@j$A-URM+ebgJk9m#g`G z54I1~0+T#(YCvPqv1*Hz*&uoT!T)7og^4*1%c|rEqgK8LH?WRE`k^$YJTbUMCmqV0 zq*P1gRV2b%ZhniUAFM2)-%!kMS~?Viv#K!8Pwv0*uoK$2%9<9IbACZqSdPpwqR*u_ z2)9oeS|L|FFW#oubNZZhzvu0%2~=U@;uDpeCG%cn4^u4Z%)a{ckonfY+&oTahSa#d z@b|s?-@MRR8*SU>8IvFgMeUB^2eyd1dQ@`0wzBmN1Lwpjc3<;y<1*<6KjQ`f{&=<6 zI-gr2Qi$&zjGlC?tKG=@-Z&ZvX4Q#kFFx+0j{lF%Sh=p2#7kjG9>p4omFss76v z+i^Y^=a?JCa~}P~y=TX#)|~V3YN8C6+Ypbh6S5z@T3FBLOwycXDqIlo087`j>@9)v zhk~$|@1wcK7|P4(chcWq4z)60LTdxtDp$ADhU8t#RY`(!==wxX&YcpJTMRVCg_X8z z%<&uT%CN2BxtsSuL$1Cx!RvQN$6*0hG8I+V#L-z&NdWoRY6_2+F@yaUF)U$Ul%fM? zQ`yq~;+i8X;Kco|LPM2Dvk*~q*e7@QVvtStnRUY9beJUAOu!pl6(eY7Vb+J_e<1jO zDqY%nsCU;l6Zgf8howejIop=am9c=OWhK6$cn0~WibvyP5R>J=TV=PlH8StiNc4>a zF$q%dx=c`PG5wyKl7%8XhveW;ME5cLhv&EAJc~gae=fU1$&Q=F9V3F}l#-=b?q6{; zo1T1@#wZ|Hrf2-m3n-(X+b2i-TqiJiUu7q!wii)4|De_yg*OSR66=|NUwySxn-lkDJ7c)BpcrEkgPUB-c1Qy^z z8)WKc3gifJ7F;ONAn}uToQE0S=6T61gwU>AOJIkpn59;haYT=8)D0dF^|~WVQoz$c zM)U_uK~UmN`;NJ)BAI`I5C5FMIKL1rU{RbpW-@RV4lc2u - -FreeType 2 Introduction - - - - - - - -http://www.freetype.org

- -

- - The FreeType Project -

An Introduction to FreeType 2

-
- -
-

- -DOCUMENT INDEX:
-

- - -

- -
-

What is FreeType 2 ?

-
- -

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.

- -

the FreeType 2 library is our new software font engine. It has been - designed to provide the following important features:

- -
    -

  • - A universal and simple API to manage font files:
    -

      -

      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).

      -
    -

    • - -

  • - Support for several font formats through loadable modules:
    -

      -

      FreeType 2 uses "font drivers". 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.

      -
    -

    • - - -

  • - High-quality anti-aliasing:
    -

      -

      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) !! -

      -
    - - -
  • High portability & performance:
    -
      -

      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..). -

      -
    - -
- -

Note that the beta of FreeType 2 is available now. For more - info, check our Download page or see the source - and its diffs through our CVS Web interface. -

- - -
- -
-

Features

-
- -

Supported font formats

- -

FreeType 2 readily supports the following font formats:

- -
    -
  • TrueType files (.ttf) and collections (.ttc)
    • -
  • Type 1 font files both in ASCII (.pfa) or binary (.pfb) format
    • -
  • Type 1 Multiple Master fonts. The FreeType 2 API also provides - routines to manage design instances easily
    • -
  • Type 1 CID-keyed fonts
    • -
  • OpenType/CFF (.otf) fonts
    • -
  • CFF/Type 2 fonts
    • -
  • Adobe CEF fonts (.cef), used to embed fonts in SVG documents - with the Adobe SVG viewer plugin.
    • -
  • Windows FNT/FON bitmap fonts
    • -
- -

Note that Apple's TrueType GX fonts are supported as normal TTFs, - (the advanced tables are ignored).

- -

Besides, it's possible to add support for new font formats by providing - a specific font driver module. Modules can be added either at - build time (when recompiling the library), or at run-time; - this allows, for example, applications to register their own - font driver to support program-specific formats.

- - -

Patent-free automatic hinter

- -

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. -

- -

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.

- -

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.

- - -

Modular design:

- -

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 !!

- -

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.

- -

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.

- - -

Due to its very flexible design, it is possible to add, remove and - upgrade modules at run-time.

- - - -

Advanced glyph management

- -

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).

- -

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). -

- - - -

Advanced font access

- -

The FreeType 2 API is useful to retrieve advanced information from - various fonts:

- -
    -
  • vertical metrics are available whenever found in the font file
    • - -
  • 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.
    • - -
  • provides ASCII glyph names whenever available in the font - (TrueType, OpenType, Type1, etc..)
    • - -
  • 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...
    • - -
  • 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.
    • -
- - -

Simple & clean API

- -

The FreeType 2 high-level API is simple and straightforward, as it - has been specifically designed to make the most commmon font operations - easy

- -

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 !!

- -

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

- - -

Robust & Portable code

- -

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.

- -

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..

- -

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 ).

- - -

Open Source & Vendor Independence

- -

Finally, FreeType 2 is released under its own BSD-like open source - license, one of the less restricting licenses available, and this - means that:

- -
    -

  • - It can be included in all kinds of products, be they proprietary - or not. -

    • - -

  • - 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). -

    • -
- -

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).

- -
- -
-

Requirements

-
- -

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.

- -

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.

- -

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.

- -

Please visit our - Download section to access the software archives.

- - - -
- -
-

Patents issues

-
- -

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 entirely patent-free !!

- -

Note that in order to compile the interpreter, one needs to define - the configuration macro TT_CONFIG_OPTION_BYTECODE_INTERPRETER configuration - macro in the file "ftoption.h". 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 contact - Apple legal department for licensing conditions, depending on your - location and the places you distribute/sell your products.

- -

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..

- -
- -

-

-Back to FreeType homepage

- -

- - diff --git a/docs/ft2faq.html b/docs/ft2faq.html deleted file mode 100644 index 2442395e7..000000000 --- a/docs/ft2faq.html +++ /dev/null @@ -1,729 +0,0 @@ - - - - - - FreeType 2 FAQ - - - - - -http://www.freetype.org

- -

- - The FreeType Project -

The FreeType 2 FAQ

- - -
- - -
- -

- - Document index - -

- -

- - - - -
-

- General questions & answers -

-
- - -

- I.1 I though the FreeType project was dead. Is this true? -

- -

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).

- -

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.

- -
- -

- I.2 Why did it take so long to release FreeType 2? -

- -

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 :-)

- -

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

- -

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 Catharon Productions, - Inc. for their commitment to this project.

- -

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.

- -
- -

- I.3 Is FreeType 2 a Unix-only project? -

- -

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 AtheOS screenshots for examples).

- -

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.

- -
- -

- I.4 When will X11/XFree support anti-aliased text? -

- -

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 :-)

- -

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:

- -
    -
  • - 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. -
    • -
  • - 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. -
    • -
- -

As both the font and rendering models of X11 are limited, it is - basically impossible to draw anti-aliased glyphs without performing - huge hacks within the server.

- -

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.

- -
- -

- I.5 Is FreeType 2 backwards compatible with FreeType 1.x? -

- -

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).

- -

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.

- -
- -

- I.6 Can I use FreeType 2 to edit fonts or create new ones? -

- -

The answer is a definitive no, because the library was - specifically designed to read font files with small code size - and very low memory usage.

- -

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.

- -

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.

-
- -
- - - - -
-

- Compilation & Configuration -

-
- - -

- II.1 How do I compile the FreeType 2 library? -

- -

The library can be compiled in various ways, and a detailed - documentation is available in the file freetype2/docs/BUILD. - However, we will summarize the process to a few cases:

- -

- a. Using the command-line 2 build system -

- -

The engine comes with a sophisticated build system that is used to - configure and compile a build of the library. You will need GNU - Make installed on your platform (Note: It will - not work with other Make tools).

- -

Basically, you will need to invoke make 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:

- -
    -
  • - make visualc will select the Visual  C++ - compiler -
    • -
  • - make lcc will select the Win32-lcc compiler -
    • -
- -

Note that on Unix, when the first time make is called, a configure - script located in freetype2/builds/unix will be run in order - to automatically detect the platform & compiler.

- -

A summary will be displayed showing the detected platform and - compiler selected. You will then be able to start the build by - invoking make a second time. In case of problem, consult the - BUILD document.

- -

- b. Direct compilation -

- -

You can also directly compile the library from the command line by - using these simple rules:

- -
    -
  • - You should place the directories freetype2/include and - freetype2/src in your include path in order to compile - any component of the library. You can also add the - system-specific build directory (i.e. - builds/system/) 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). -
    • -
  • - The components of the library are located in sub-directories of - src, for example: src/base, - src/truetype, etc. -
    • -
  • - Each component is normally compiled through a single C file that - wraps other sources in the component's directory. For - example, you should build the TrueType font driver by compiling - the file src/truetype/truetype.c. The list of - C files to compile for a feature-complete build of the - library is given in the BUILD document. -
    • -
- -

- c. Using a graphical IDE -

- -

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.

- -
- -

- II.2 How do I configure my build of the library? -

- -

Each build of the library is configured through two header files - located in include/freetype/config:

- -
    -
  • - ftoption.h -
    - 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. -
    • -
  • - ftmodule.h -
    - This file contains the list of all the modules that are initially - registered (added) when the function FT_Init_FreeType() is - called. See the next answer to know how to change it and why it may - be important. -
    • -
- -

Alternatively, some specific implementations of some FreeType 2 - components can be provided in a builds/system/ - directory (e.g. the Unix-specific ftsystem.c that uses - memory-mapped file for i/o).

- -
- -

- II.3 How do I select the modules I need in my build? -

- -

The function FT_Init_FreeType() 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 src/base/ftinit.c.

- -

The list of default modules used by ftinit.c is located in - the configuration file include/freetype/config/ftmodule.h. - Normally, it is automatically generated by the build system by invoking - the "make modules" 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 src that contain a file named - module.mk.

- -

Note that a specific port or project is free to provide its own - implementation of ftinit.c in order to ensure a different - initialization sequence. For example, one could do something like:

- -
    -
  • - Compile each module as a shared library (DLL or .so) with a - common "entry point" to retrieve a pointer to its module class - (there is already some code that allows this when compiling each - module). -
    • -
  • - Place these modules in a directory like - /usr/lib/freetype2/modules/. -
    • -
  • - Provide an implementation of ftinit.c that would scan the - directory for valid modules. -
    • -
- -

This example only emphasizes the flexibility that is left to - developers when building the library.

- -
- -

- II.4 How do I compile all FreeType 2 files in a single - directory? -

- -

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.

- -

To do so, you have to copy all source files located under - src 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 FT_FLAT_COMPILE. This will change the - way #include works during the build.

- -
- -
- - - - -
-

- The FreeType 2 auto-hinter -

-
- - -

- III.1 Under which license is the FreeType 2 auto-hinter released? -

- -

The auto-hinter was initially designed and implemented under contract - for Catharon Productions, Inc - which gladly accepted to released it under an open-source license - compatible with the FreeType one.

- -

This license can be found in - src/autohint/CatharonLicense.txt and requires that you cite - Catharon Productions in your documentation (just like you do with - FreeType) when using the auto-hinting module.

- -

Other than that, you still have the same freedom than with the good - old FreeType license. Enjoy!

- -
- -

- III.2 How does the auto-hinter work? -

- -

Well, a complete description would be difficult. Have a look at the - dedicated auto-hinter pages 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 :-)

- -

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 - FT_LOAD_FORCE_AUTOHINT bit flag when calling - FT_Load_Glyph().

- -

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.

- -
- -

- III.3 Why does the auto-hinter doesn't work correctly with CJK - fonts? -

- -

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).

- -

We thus plan to handle such a case in the near future. Please be - patient.

-
- -
- - - - -
-

- Other questions -

-
- - -

- IV.1 Can I use FreeType to draw text on a pixmap with arbitratry depth? -

- -

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.

- -

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 direct - rendering. For more information, please read the documentation - contained in the following files:

- -
    -
  • -

    <freetype/ftimage.h> contains the definition of - the FT_Raster_Params type used with direct rendering.

    -
    • -
  • -

    <freetype/ftoutln.h> contains the definition of - the FT_Outline_Render() function that can be used to - convert vectorial outlines to span lists.

    -
    • -
- -

Here's some code that uses them:

- - 
-    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 );
- - -

Note that direct rendering is not available with monochrome - output, as the current renderer uses a two-pass algorithm to generate - glyphs with correct drop-out control.

- -
- -

- IV.2 How can I set the color of text rendered by FreeType? -

- -

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.

- -

Note that for anti-aliased glyphs, you can "set the color" by using - direct rendering as described in this - answer.

- -
- -

- IV.3 I set the pixel size to 8x8, but the resulting glyphs are larger - (or smaller) than that. Why? -

- -

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 PCF or BDF.

- -

Be aware that the character size that is set either through - FT_Set_Char_Size() or FT_Set_Pixel_Sizes() isn't - directly related to the dimension of the glyph bitmaps generated.

- -

Rather, the character size is indeed the size of an abstract - square, called the 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 - distinct dimensions!

- -

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.

- -
- -

- IV.4 How can I compute the bounding box of a given string of text - without loading its glyphs before? -

- -

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...)

- -
- -

- IV.5 Which anti-aliasing algorithm is used by FreeType 2?

- -

The algorithm has been specifically designed for FreeType. It is - based on ideas that were originally found in the implementation of the - libArt graphics library to - compute the exact pixel coverage of a vector image with - absolutely no sub-sampling/filtering.

- -

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.

- -

The FreeType 2 anti-aliasing renderer is indeed faster - 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).

- -

We will try to document its design in a later document, though this - is not a priority for now.

- -
- -

- IV.6 When will FreeType 2 support OpenType? -

- -

Well, the engine already reads OpenType/CFF files perfectly. What it - doesn't do is handle "OpenType Layout" tables yet.

- -

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 ftstrtto to show its capabilities.

- -

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.

- -
- -

- - Back to FreeType homepage

- -

- - diff --git a/docs/glyphs/Image1.png b/docs/glyphs/Image1.png deleted file mode 100644 index acffdcd0bbf1f2e7a801d76d09e4f12a99f4aa34..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2926 zcmV-!3z77RP)3nNKHK~#9!?OI=K+r}BcBWaOxSd+4ifdMj+lI=hl96)Kh&Bcs}QrtjJ z+rbO^kZvz_6JTk#2c-oD1@SCOR&DPOI;H6VuPu-^EsDOaF9SAUz^E8#S}f}yU;{R+ z56m)PZw-q+R09Na-|>$mQlg|d-G(kZDAIlW@pt##ci-K8_c;jlEGohXVTPm7G)N5M zJRn6dQbdg1N|2lNDl6`*DDmFM*9)ZbYHIP2{UkP$$*s1%CrIgf5>`@PWkyvvvD^}8?eA$%e0?i~pYtl$kUREkfB4he2B{>ME-jKL zI5}I>ZD>4lDNicY_$jBtjr?k5QnUHk)tQNVHp8t^bX##y0Rm~35fQI~;ka4^ebYCA zh*J9TRj-1XBQ;!$abYix`Nedk!}w56gSAKzEq;{X-Dzg*z`4ohUULoR}>clg8hea1gOIbzN?Jy|%mzFL0lRz0t5?`XU%0Yg0iRRH{QK` z_I3R)_Z{SKES}Z>`0I_!Us;f5o+Pu1shs*QQf3q`DosCHoi#M51me#;%sCk`N}4%&CUC`xNM?Tc1Kf-^lQ)2`tmU!N^2%6 z(mT*Rt&h>V!TV4abSmPT4L~&{)OEjBtkne6C}{+}6-0RyCn#$G%F>{s50$`JMXVze z&;x*C)<3fXG+J>{y%F)D1;pw_me!2oaZMK9DK*)xcARp)f#grGG`?YNW=c2TzxkPL z-ZI<1P_Ty#MrKg~+X@@bN#9+xe!&k%LL;ijQ-nqlS<19!=>e2-QA+C-ScwSr54wmx zirqq2fzC|$GT%J{fC`i7XtPeP=#^h#Pf zMb3qjXRlAZG#!1UOi8Ej|INfc<7p?tQmP?O6%A`%LWxdWk5AV z(0RIS`q2V3Re(swLm9!pt_4t+a!^)l@;=lcQBZ`&MsZV%3tOdzz)?O_Uxm;~FKue_ zr{Ec^+4ksL5CwfEH!fPwWp3BszxAizs*Q9d;@at3A8; znnLBqD-&w|WHR;lM2)+dI-Gyep$fIE^oYVwPoN5uoy?9VIVQG%HpbITa*A1@Ci6Pl zh%sqRTv!&X@Gr+rMV(}#M2RQFErnZ9#0rxWv)q)(Bp6g3N8Exsi77FUFrQ!)O{r2b zZUIRZ?pn+lV1!amCB(eAv5;W4&MMD~c`cHQ;?%)3_v~ZSPcX{%+jz1P%_>Q*nh>kY z3^TfrjJ8A5&f6z8x&pF5ilZa<$@!>ViC}-2tEjlWz2chMxgkdS=lIgv{oMcBs)*R1 zR!F4`LD5_XWjYQjhT@ew=(Upy3uoZ&O>dkL=(!bxeK}o3X7R%2%jvm7{HQd4?6@$1 z%H_&Rd3;)lMPnS5;FL?z*r>=QxT<(QF@P$bpp=SqT%Y2T67z(VgJiVuJ+IOzZo~Q*oOSva%!@bz;AeES*<&-9hUJf`Kf}|o%9a7tY>r|waZ|oQ0jcf@DYMDjIB`Ws%+X+3w|=Y zY1XoIR=2= ztTBj6GGN4=94fX1LH|VK~#9!?U+B0(?}SH$99M#WH}L4q>CVjI0-1wL=;5FYU5=Q0fF|m zq*$SJcMVb`niP?CiYvGV?MI-bMOR#jJ6b-1CHMeF*QChB=XjjV&-O3c<w*V0(lV*{ZBI7({+1_gQD2TrSpu>^U){Ql_kVkwn$7F$nj>!oZ_*PWxgA9WX~ ztW()Wx}IK57P?!y>nSaD*TcB-@2$!O-L-Y+>drboX8UAYYkYDW2eAE|C#Q>F0@|OUWc}ywVkZ> zv-UiEx>cItWarj_^ZAStoIZ~r+r3rbK^}Pn#x#T(yyV!hH8bo?4A&0~dwYi4L&KL6 zwdU@w;b13Ra~MRLuM0OG&P@yvQ4Uy9eKWl=C@Q%PZwc^mX#hxo_BdSA5cbmlB+P9sx_Z zUfKQo^rtsTTIMjO4Lk-8*!&^S0Sh?>9>cW;wkL+`z_qDi?*M+Co)~WLah5~Fg9Lu& zhsvbYuHgVU+%X$dhAp*|Z|u&J*Bdj>96X

3qWDuU8%TBJdMn|4SIo)?Wa_`80n4 z4`=1?o(2of_aL4}kTWqmw>ulo^9pc#^R);+?VhqeKs=D2HHgzgz6<*Tc41vN+OS7R zD*$p6M3XNb(B1;T35(H)i%>hrYg20WHYSTerltNoe1g16+0HvnN@5gq%|*F zXK8U8%m2EF<}95TL#rLJe6Yh}g6Y!v`^D?G{r8<&In7md?8?fM+bOfnIkOhE;v3t+ zjM-#C>^~n9Vi&TM?D=Y!s4Zs6%DSgzc?{etW-rnmZxK8A7!g~3mTbtK*6+;fye?b& zC9_sYa{bwh9?A7CeR_T^>n1U=ogTA&IVN@@C9zZ4BKDBRFo>CLCd^t%#P(LYFLHZx zPHZ5V9my%NV>zKaW~X!bXCbm$_AgYiTg)i?GQAeBs2$TMBF_@R#{LK1cRb17jQt+7 o?q7=7>OEii1ICoeS$M_%7u;V%DfV~>fdBvi07*qoM6N<$f?4qpj{pDw diff --git a/docs/glyphs/Image3.png b/docs/glyphs/Image3.png deleted file mode 100644 index a4820897f67d2276a7788d32158d204ecfa76ab3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3020 zcmV;-3p4bIP)3xP>QK~#9!?OI)I97i3W+1MclRG<3utJc|C9V9BoEYN-D|OwZI8U{b6g5Fec>(c&#KsMwyigu!g?QSa zq6nU@@Ny5QTjpbTZ}wx>d$f@d%E-CB+28zT{xkoN`OjPc@D{~-=HWbK-%&J^B(efmSx6r;17-Rdmsu0g z?5IdoJ^@h+`~pz495)pJhMrr!qWN3q@jv9$RLdBg8jqyQ()H^#EDP zD|Kr|fCvhLn!R{F4ibpSau6x7H+OxX7jYtfPD33;#*qZE0HI5#?{J)Ba?|3#qQZ{@ zo4_=KWP@@8)IEqql!IWx0A+*}-d7}La~Ppm+5iO|xl;gTbFhM91&kOd`RCXmkKsjz z3{lq)#=R0Sgox}#(hV|Bkkko`py2s5K{-&T5VS!{fD~}RK-6;;53*osVNY_{GmafX zQy23d*^sR{$v+ zKv=yg?>KuI5+K15A##qyXat})W+F%|YSF`yrry9vy#*59nZ~AfS!;k;Z;}RPSsMkB zwI;gR!+)agyDiahw?vJZjYjUS1!Bw#v47%6&$2n<4mnMkIHY69flB^1!x z<3bd_PETb)tA<>0m5W!&{aDkv!^BJ7kqjoW2Bh3cAPwSuj`v~dP!bbQyaxZ*WyW>OVSEggb8)HL0C(|bGorv|E87uniMa8=& z>`}%Ce5s2vHNBy3{_MiQj%ltK;jB#RkGKcRx(G=S=_^4wR*cwsEQqrkH$V83KLwo^ zNrsIy0Wx$D2#}stBtQh`(lDeLyqJ)Awi1LuL8oDexHpdkb3&<$Lgau5NsUhZPv zHvamJ?|kLvuQu*aUgtOo(}{CP$$pJP3Z`x$P>+3ljYH1iom<-S#%O{x@lbYeE(A7! z0Fi|V&RyzlH-hty#0W!xm!p#4ktX>Lxf)67TyGEpjUnU|fovpk=HWUXr=Wu}Z5?xZ zgJ5H3$!s&^^6x$zbdcoRu`R~If9K)QmV=}|8kl+jG=^L~w5!6;XWijkyFGq67(q09 za<2i&tHKfgx``2z^Pym*!B!_g3m5^xNHahSOs7q7E*OC=&qFE<$#rOotM*&JB_W=;Q70pKhDj*qgNW$a`@^Hwy)yZLA_V$*b zCw{yXy-gF0?=2K*0XCK&X_Lzx zFQO2H*x_Oz2S-uZ@F4Ita@MUki9@=P*oh=T@G9%x-lUpiAvVHx3}yWku{WYPtL2ux zW5lRkckXR4=YXB-5-+Jc!vK^T*ZF;+*~xX|lR3dIqhxgf68reQ&$c^%2E@DBLdSI5 z(K(;LYM%8L^@^!Nnw|6UTv4n%v!iN4!9m&UAb@mRDm z;I?f@iDV?g@ZTmby-2^^xR~u3#sN|O*IpV;(`<+EmAF)0euiB`_Y4k_xSx-ctB?}j z9rA&WmQ)rlJB38&Rvs;82Q>WrIGi+ z!1`SyKZ=*3-*>I*xz4DSUOilzy-+FYch5gvimzo-Aq;j)Zy2SzoPdoVH=3ih-o$nz zf?6xJP}n1tZ2C&HW2w;8jfj`QP9gVtOsdgTG{({2*e85#HJVgsFFRKnYP2!PQ5{Q_ zoVYRgM05sO;OfNqNJN)qW5l*@{e8SEsdmG)wYBJDbXTk~y3inHsJ=7vPEu7wDS(I} z^QrJ78l!V9P(+`@TBYLM>LZm5XZZMo*~7iHN;gtvv-1bC!Si6hN+Q5}G44AzxICo> zGU)M$Tqg5BTH!bOS@jqDgBWQO(QFV&RW2%3K|sj08098C2epwp&LzMTLHEFn0ZHo5 ztb}XAv%QQ2F(@A+_@bFH(k4A0cflyP>D>+jAq<7SP$b5vlLJxO)WaA|D^eaa;u0_! zgB(~Z8oTMzyo|n7|Mc2@SRrF<1A0P9(1WaX$*B3R*hhw@zkTo;M1=7)OB<3XgRT+wUV>T*H*(AiH3)v3?{35j5!B(;bV-NZY1+ZbzwVj8V23uSXrD zZb=23JI~x=v}_~WfuTtj!#*MwjHpsEDBDxx@G*vFtHW39=wly|U1QM9G8N|%36n`gK~#9!?OI=K97h?S*<0VP&BnJrOmz*eZ+$)qH%+7q1u2zGZ=JZp zE)g=uNPu{_xF9v^i%W#CAkA$OBb^~a`9~GrOygE*)d!HO0761*HKG#a0a4(g;$chs z02L2co-We$mYLbz+1Z)7-Az&fLX70q+;4v~^Ue2t^L;b327oQ6*&ic-D+K^7`U9dr z6Tk)lje>#!y^Eifmi%eBgadwx5n!Wd)x$`Mv@*^3*)R(`=q=_eLC>5F;o!79ARtVc zBu|w*Yh*?W`4My+J@K@ZkD#X>)HQ;S5!v<=$;&pW+c7fckSF1n37?%&narg|o}aXe zt!PF?Adb#IYwK}cQfw!xeX|myYB)(!HRCEsR2!r^9&^;VojS4}R2>YFYUwKYmP;*u zt4*!2wHa5B(CRH(h3{_Af!lEpTL82oE_J4YKZprhR8>@J(s32(0`A9E?cMp1X+qx% z-#fxI<7%jhaT#GUt`?2aIq+eXXP>53qZPwCGc-IEdvs(@lS+%Iu?Z8Vr?q|f5h!qq ztg^T&Yf0Db*g>1qghJhkt&aW;G_e?%_IvP7Y(m$M1s}v!YHrQhyq9Xh-H5AQI-2Lj zZsdgWV1p~`Gzw`9}fSHjhMy&p4H zM_4h8QSr9TVx5eX0m6c~1Rsu=zH31upYn>e8->+`&xZ5G;xWFVGzc+4n>a46nfjrj z>*zkPO%Z~F%Wr+|Qy*o2z(y+s~-WM#4=3{u}K^H9ycaY~Y+95FShj?_lVR}Kg^8hLA4 zi0yD;i5mg6y;cof3WF(8F5`Kt&m0iiuKsES@NJEyHG#MN=AtEzQG|Mkp`&Do zLE2V#BbkffqDd7N$p=~?_JmshIZ?==-J6%qD2JjsX#>=oL;HLFAZpw6T^4)nJzD{% zKhcHCPK04wE3h|EDu{d2}Y$~C9l&AT5Aj}tZkFfV8*d1P{2>XE7 zsSG>s3%*-G^Jw$^kv&Zk8%J1)!=@zIyaYQ%B(J} z+QNA-DX_9_TPRm0#y)xt)}fj_!~Q@y`zmWg2rGR_m~=RaCGR|aq9vT#rFJ`)YRN(v{q*i1U&&-0HkUhJAEpX3V%4mdCci(7; zw35qSvcurUhL^tJI|A#pI7jwQCuDhYeN6?|G1I#2+f!sAVj>&pm24LJY3oD3V`0`q zll4FUX!$%y?`w9hvtV3NKzd(`3!gf7>39}viB!UHS|nwNG?Dg21U25es!ugo+q2CU%Y5R8n+vVJmIYuSVagR3tH;EKR{U4P=_ z9AQ=ceK-a{pe*q$=ul0xyGDuZl=Y)LOQHHgK4_2wdbIVDYPIA817@}8LS%te`X=q=Z#?t-+tX>XQ;jUO-hF1HzSOcO} zH^bTiE8W`IX|T03JO{Z0@~?gd3khxjznj5AlQeK%NM|9zZZ`+yrS0O+$#PaT$P}1` zCTd%9)|mpiuZO`$b=#K9)eB+{db#k0Cy(E7|`OS$7305e*7TZx-KT!YEVx3`)U=PHs<{o9Kw-=W$bT$$! zKUhP4>|bNQ{oTj5pIl0eNTM95_EWtO=g$i$qNK;@$i1A5NFKQTkTo=q|0w~l?Qjzd zfxalRj4?g-)q#B10l@fV7{5xvM@Y1TX$h>=a((s2kvFRG&iS3G4S_XTUYxlo*;yr7 zmD#P;IhF-wtcg31-)c!u6i~cY$r#b$S<(@QpJ7t>tNHr+kVb4KUe1{EzQ`GdvPLcW z#X|D%GvY``EJSR-~6cKddjkxI#Wq*}-W=T3YqaF{^N413(y@R-|R;v-<7|yzPPd_29H3E8`#k o=W`u5+m3+xYG#@KU%c7-7fDcQCKCV?g#Z8m07*qoM6N<$f*r@y{Qv*} diff --git a/docs/glyphs/bbox1.png b/docs/glyphs/bbox1.png deleted file mode 100644 index d39ee24e48688d2ce969967942d753b2188182d0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2888 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 MrJY5!nNQ-s00D*^mjD0& diff --git a/docs/glyphs/bbox2.png b/docs/glyphs/bbox2.png deleted file mode 100644 index a8069b18cd7a05a77f4c92a37da3efe4bc27f30f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2722 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 diff --git a/docs/glyphs/bravo_kerned.png b/docs/glyphs/bravo_kerned.png deleted file mode 100644 index d8452d37427466dcade786abc637c99e860054f7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1316 zcmeAS@N?(olHy`uVBq!ia0vp^*+8ty!OXzG$ZB$Z3j+f)Lx4|+D^PG0P#yxgxuLna zt0*^z7!xK<3Y|2GPIdv^vu)d|ZQK46bLC9FFws#~YeOa3Ck?Z3&e zu(oxJu3~fE>!xcHTH^SEgu|uTy1&YOeUE%H;nDjF`fDUOW`_RWzxn&xonIEe<}JCHr}*~Kv)G2PXyI>) z`vRA~=?!4pb|b1rYv#)b;v1G+ZIS$-abah0lSB4QLB>iCaU-_G$M^cD8~NQV3-mhY z(R8k4t??WQ7VhfJ(|@jB(UB|JUaj};r>b(%zka5tO{p{AR4=r@bk#Li_^`;DCPOcq z{5h=|mG$1&U%cyBmc3`eOEa5n!&x^w=G^Rm+U9b`CWKA=b&yz5LK6Q>!BRyY<2r|R wGB>*J8^jz`$htcz;9A+CKVJ^_uX8_c?lbvjq2igHi$O`$)78&qol`;+0P9T+rT_o{ diff --git a/docs/glyphs/bravo_unkerned.png b/docs/glyphs/bravo_unkerned.png deleted file mode 100644 index 11821070cf1071edd19f06318e469e8647c1feb3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1321 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 diff --git a/docs/glyphs/down_flow.png b/docs/glyphs/down_flow.png deleted file mode 100644 index 2b3f95fea78c5d2475f84d1be861d6a8bf63358d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2233 zcma)82~<;Vu6Bx+^~zYGEiNC1y8cpos6D0d4Cyo7>bX0~8pM1noAAP_jn3~po__GoUT{ulBE z$-P#-4RQ&rRQ?*t@>Uo=Bl%&S#<6k1;#0&5U$bP8ff=DBmar8`b1fIHGuqi$5d&52 zmpBH6-@%FtKw&~y@c$2V7qX&v*5>9as;fdqOg?z~Q)xpi6fAEKeTT;>V{m&K&IPGL zmINkq*~1bcVUcs82u|jv4vls@+BcJ1LL-H4R#Mt>Hyhhrhv!qqwozM)LvB0I4MQX5 zLVuexpbuT=a0V(2{aToZ)0-0VJkfrQaTRWse&s2i^hlI&|NNR^^j35@eGPF|Ka?Nb z`ZOjt&h$(pAzBUGe)aqJp4!Wh--KqY5q3>7LuPB{$88B0r;PC!rAbB~y85tC1UaqB zU%`QakJ9@wvvPum;=NQ4)rR^>I+>^!GNyo+mU{fLhlHa&5N1ppe&2ys{5P-Oz7@|Ooro2!!^E&(r7$b<9&&;$JLI?4eeZ638>Yp!LPSn`ki$= zq@l!qr$MpSg!__Et4^!%%AlK%#baPkyn7tA8HsX1+n}lc5I%yy(K5b zn^h=V0!SMcxeg(NzNnC-lbpI_u^1giUi6kwdcr?#>KRI?Yu`)rVaNr zoY0Vi>SnT$7es-QCLdSG*jk}2JXDBn?WzXd5Hq`j-Nh6bGv*wqAwV; zxE&a-ifBn10=2qK-}pTZuOSVMh;lN{nOJPL*J5TVC8*0v`kKP!%`sRETvpQBBo(q0 z=3}bC>TcA0V1u&oAS=j9R#6O3`%omi?!RL#3C11Pl!3}hss?h4PsinI9M{dBZmwgG zWhm1F&96Yu%e$R$1!d(zq<{pYcueP32;htuZ*>9^$oiko6j9dTQw{`-5kjv3;_sQ7rj z{WvilQI}6Uin(_xzAGJa9GisD}%de((rKR=*U+~u zXH>WW$qfYfM=ITTjkGUMr6ecxsM2>_62L1t(+I&ABq`p7_V1z!EYZn!P~y!??-(!l zz*M+Z;xU4b`;&BFLb7jf1tsac7TN7DAN|AK$x&C$z*5nt{r5wG*4>npZm%vxfiMA2 zt9bT(lyxF-mX|y2q#IpE>e>JNlWW`5$Um^awr|OFW&lWjO7jRV(i z2znA68$;fY%b~b-Khr!PCu-u`a}aL(nIHVs^>(!*ZbyKoAwfuML=f%uz;7r HuEqWV8B*ux diff --git a/docs/glyphs/glyphs-1.html b/docs/glyphs/glyphs-1.html deleted file mode 100644 index 9fd7e7d5f..000000000 --- a/docs/glyphs/glyphs-1.html +++ /dev/null @@ -1,199 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
-   - - Contents - - Next -
-
- -

- - - -
-

- I. Basic typographic concepts -

-
- - -

- 1. Font files, format and information -

- -

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 font family and its - multiple font faces, which usually differ in style though come - from the same template.

- - For example, "Palatino Regular" and "Palatino Italic" are two distinct - faces from the same famous family, called "Palatino" - itself.

- -

The single term font 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. - arial.ttf for "Arial Regular", ariali.ttf for "Arial - Italic", etc.). The file is also called a "font" but really contains a - font face.

- -

A digital font is thus a data file that may contain one - or more font faces. 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.

- -

As a convenience, a font file containing more than one face is called - a font collection. 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.

- - - -

- 2. Character images and mappings -

- -

The character images are called glyphs. 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:

- -
    -
  • -

    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.

    -
    • -
  • -

    The font file contains one or more tables, called a character - map (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.

    -
    • -
- - - -

- 3. Character and font metrics -

- -

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.

- -

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.

- -

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.

- - -

- -
- - - - - - -
-   - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/glyphs/glyphs-2.html b/docs/glyphs/glyphs-2.html deleted file mode 100644 index dc2b2b9f4..000000000 --- a/docs/glyphs/glyphs-2.html +++ /dev/null @@ -1,397 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- II. Glyph outlines -

-
- -

This section describes the way scalable representations of glyph - images, called outlines, are used by FreeType as well as client - applications.

- - -

- 1. Pixels, points and device resolutions -

- -

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.

- -

It is thus common to define a device's characteristics through two - numbers expressed in dpi (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.

- -

As a consequence, the size of text is usually given in - points, rather than device-specific pixels. Points are a - simple physical 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.

- -

It is thus possible to compute the size of text in pixels from the - size in points with the following formula:

- -
- pixel_size = point_size * resolution / 72 -
- -

The resolution is expressed in dpi. Since horizontal and - vertical resolutions may differ, a single point size usually defines a - different text width and height in pixels.

- -

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).

- - - -

- 2. Vectorial representation -

- -

The source format of outlines is a collection of closed paths called - contours. Each contour delimits an outer or inner - region of the glyph, and can be made of either line - segments or Bézier arcs.

- -

The arcs are defined through control points, and can be - either second-order (these are conic Béziers) or - third-order (cubic Béziers) polynomials, depending on - the font format. Note that conic Béziers are usually called - quadratic 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.

- -

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).

- -

The grid is always oriented like the traditional mathematical - two-dimensional plane, i.e., the X axis from the left to the - right, and the Y axis from bottom to top.

- -

In creating the glyph outlines, a type designer uses an imaginary - square called the EM square. 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:

- -
    -
  • -

    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:

    - -

    - pixel_size = point_size * resolution / 72
    - pixel_coord = grid_coord * pixel_size / EM_size -

    -
    • -
  • -

    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.

    -
    • -
- -

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.

- -

Grid units are very often called font units or EM - units.

- -

As said before, pixel_size 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: - -

- Comparison of font heights -

- -

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.

- - - -

- 3. Hinting and Bitmap rendering -

- -

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".

- -

As a consequence, proper glyph rendering needs the scaled points to - be aligned along the target device pixel grid, through an operation - called grid-fitting (often calledhinting). 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.

- -

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:

- -
    -
  • -

    explicit grid-fitting

    - -

    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.

    -
    • -
  • -

    implicit grid-fitting (also called hinting)

    - -

    The Type 1 format takes a much simpler approach: Each glyph - is made of an outline as well as several pieces called - hints 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.

    -
    • -
  • -

    automatic grid-fitting

    - -

    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.

    -
    • -
- -

The following table summarises the pros and cons of each scheme.

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
- grid-fitting scheme -
- 		-
- advantages -
- 		-
- disadvantages -
-
-
- explicit -
- 		-

Quality. Excellent results at small sizes are possible. - This is very important for screen display.

- -

Consistency. All renderers produce the same glyph - bitmaps.

- 		-

Speed. Intepreting bytecode can be slow if the glyph - programs are complex.

- -

Size. Glyph programs can be long.

- -

Technical difficulty. - It is extremely difficult to write good hinting - programs. Very few tools available.

-
-
- implicit -
- 		-

Size. Hints are usually much smaller than explicit glyph - programs.

- -

Speed. - Grid-fitting is usually a fast process.

- 		-

Quality. Often questionable at small sizes. Better with - anti-aliasing though.

- -

Inconsistency. Results can vary between different - renderers, or even distinct versions of the same engine.

-
-
- automatic -
- 		-

Size. No need for control information, resulting in - smaller font files.

- -

Speed. Depends on the grid-fitting algorithm. Usually - faster than explicit grid-fitting.

- 		-

Quality. Often questionable at small sizes. Better with - anti-aliasing though.

- -

Speed. Depends on the grid-fitting algorithm.

- -

Inconsistency. Results can vary between different - renderers, or even distinct versions of the same engine.

-
-
- -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/glyphs/glyphs-3.html b/docs/glyphs/glyphs-3.html deleted file mode 100644 index bec54e13e..000000000 --- a/docs/glyphs/glyphs-3.html +++ /dev/null @@ -1,430 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- III. Glyph metrics -

-
- - -

- 1. Baseline, pens and layouts -

- -

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 pen - position or origin, is used to locate glyphs.

- -

Each layout uses a different convention for glyph placement:

- -
    -
  • -

    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.

    - -

    The distance between two successive pen positions is - glyph-specific and is called the advance width. Note that - its value is always positive, even for right-to-left - oriented alphabets, like Arabic. This introduces some differences - in the way text is rendered.

    - -

    The pen position is always placed on the baseline.

    - -

    - horizontal layout -

    -
    • -
  • -

    With a vertical layout, glyphs are centered around the - baseline:

    - -

    - vertical layout -

    -
    • -
- - - -

- 2. Typographic metrics and bounding boxes -

- -

A various number of face metrics are defined for all glyphs in a - given font.

- -
    -
  • -

    Ascent

    - -

    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 Y axis - upwards.

    -
    • - -
  • -

    Descent

    - -

    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.

    -
    • - -
  • -

    Linegap

    - -

    The distance that must be placed between two lines of text. The - baseline-to-baseline distance should be computed as: - -

    - ascent - descent + linegap -

    - -

    if you use the typographic values.

    -
    • -
- -

Other, simpler metrics are:

- -
    -
  • -

    The glyph's bounding box, also called bbox

    - -

    This is an imaginary box that encloses all glyphs from the font, - usually as tightly as possible. It is represented by four fields, - namely xMin, yMin, xMax, and - yMax, 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).

    - -

    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.

    -
    • - -
  • -

    Internal leading

    - -

    This concept comes directly from the world of traditional - typography. It represents the amount of space within the - leading which is reserved for glyph features that lay - outside of the EM square (like accentuation). It usually can be - computed as:

    - -

    - internal leading = ascent - descent - EM_size -

    -
    • - -
  • -

    External leading

    - -

    This is another name for the line gap.

    -
    • -
- - - -

- 3. Bearings and Advances -

- - Each glyph has also distances called bearings and - advances. 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: - -
    -
  • -

    Left side bearing or bearingX

    - -

    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.

    -
    • - -
  • -

    Top side bearing or bearingY

    - -

    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.

    -
    • - -
  • -

    Advance width or advanceX

    - -

    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.

    -
    • - -
  • -

    Advance height advanceY

    - -

    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.

    -
    • - -
  • -

    Glyph width

    - -

    The glyph's horizontal extent. For unscaled font coordinates, it - is bbox.xMax-bbox.xMin. For scaled glyphs, its computation - requests specific care, described in the grid-fitting chapter - below.

    -
    • - -
  • -

    Glyph height - -

    The glyph's vertical extent. For unscaled font coordinates, it is - bbox.yMax-bbox.yMin. For scaled glyphs, its computation - requests specific care, described in the grid-fitting chapter - below.

    -
    • - -
  • -

    Right side bearing

    - -

    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:

    - -

    - advance_width - left_side_bearing - (xMax-xMin) -

    -
    • -
- -

Here is a picture giving all the details for horizontal metrics: - -

- horizontal glyph metrics -

- -

And here is another one for the vertical metrics:

- -

- vertical glyph metrics -

- - - -

- 4. The effects of grid-fitting -

- -

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.

- -

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.

- -

The glyph metrics are also influenced by the grid-fitting process: - -

    -
  • - 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. -
    • -
  • - The image's bounding box is modified, thus modifying the bearings. -
    • -
  • - 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. -
    • -
- -

This has some implications:

- -
    -
  • - 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. -
    • - -
  • - 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. -
    • -
  • - 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. -
    • -
- - - -

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 exclusively using integer pixel - distances (which means that the parameters to the - FT_Translate_Outline() API should all be multiples - of 64, as the point coordinates are in 26.6 fixed float - format).

- -

Otherwise, the translation will simply ruin the hinter's - work, resulting in a very low quality bitmaps!

- - - - -

- 5. Text widths and bounding box -

- -

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.

- -

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. - -

The same conventions apply to strings of text. This means that: - -

    -
  • - 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. -
    • - -
  • - The string's advance width isn't related to its bounding box - dimensions. Especially if it contains beginning and terminal spaces - or tabs. -
    • -
  • - 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. -
    • -
- -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/glyphs/glyphs-4.html b/docs/glyphs/glyphs-4.html deleted file mode 100644 index 37af0405f..000000000 --- a/docs/glyphs/glyphs-4.html +++ /dev/null @@ -1,231 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- IV. Kerning -

-
- -

The term kerning 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.

- - - -

- 1. Kerning pairs -

- -

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".

- -

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.

- -

- the word 'bravo' unkerned -

- -

Compare this to the same word, where the distance between these two - letters has been slightly reduced:

- -

- the word 'bravo' with kerning -

- -

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.

- -
    -
  • -

    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.

    -
    • -
  • -

    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.

    -
    • -
  • -

    Kerning distances are expressed in grid units. They are usually - oriented in the X axis, which means that a negative - value indicates that two glyphs must be set closer in a horizontal - layout.

    -
    • -
- - - -

- 2. Applying kerning -

- -

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.

- -

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:

- -

- example for sliding dots -

- -

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:

- -

- example for too much kerning -

- -

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.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.

- -

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

- -
    -
  1. - Place the first glyph on the baseline. -
    2. -
  2. - Save the location of the pen position/origin in pen1. -
    3. -
  3. - Adjust the pen position with the kerning distance between the first - and second glyph. -
    4. -
  4. - Place the second glyph and compute the next pen position/origin in - pen2. -
    5. -
  5. - Use pen1 as the next pen position if it is beyond - pen2, use pen2 otherwise. -
    6. -
- - -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/glyphs/glyphs-5.html b/docs/glyphs/glyphs-5.html deleted file mode 100644 index 4dbb7e7cc..000000000 --- a/docs/glyphs/glyphs-5.html +++ /dev/null @@ -1,484 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- V. Text processing -

-
- -

This section demonstrates how to use the concepts previously defined - to render text, whatever the layout you use.

- - - -

- 1. Writing simple text strings -

- -

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: - - -

    -
  1. - Convert the character string into a series of glyph - indices. -
    2. -
  2. - Place the pen to the cursor position. -
    3. -
  3. - Get or load the glyph image. -
    4. -
  4. - Translate the glyph so that its 'origin' matches the pen position. -
    5. -
  5. - Render the glyph to the target device. -
    6. -
  6. - Increment the pen position by the glyph's advance width in pixels. -
    7. -
  7. - Start over at step 3 for each of the remaining glyphs. -
    8. -
  8. - When all glyphs are done, set the text cursor to the new pen - position. -
    9. -
- - -

Note that kerning isn't part of this algorithm.

- - - -

- 2. Sub-pixel positioning -

- -

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:

- -
-
- - - diff --git a/docs/glyphs/glyphs-6.html b/docs/glyphs/glyphs-6.html deleted file mode 100644 index df9840158..000000000 --- a/docs/glyphs/glyphs-6.html +++ /dev/null @@ -1,432 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -

- - - -
-

- VI. FreeType outlines -

-
- -

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.

- - -

- 1. FreeType outline description and structure -

- -

- a. Outline curve decomposition -

- -

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.

- -

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:

- -
- - - - - - - - - - - - - - - -
- FT_Curve_Tag_On - -

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.

-
- FT_Curve_Tag_Conic - -

Used for an "off" point used to control a conic Bézier - arc.

-
- FT_Curve_Tag_Cubic - -

Used for an "off" point used to control a cubic Bézier - arc.

-
-
- -

The following rules are applied to decompose the contour's points - into segments and arcs:

- -
    -
  • - Two successive "on" points indicate a line segment joining them. -
    • -
  • - 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. -
    • -
  • - 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). -
    • -
  • - 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. -
    • -
- -

Note that it is possible to mix conic and cubic arcs in a single - contour, even though no current font driver produces such - outlines.

- -
- - - - - - - - - -
- segment example - - conic arc example -
- cubic arc example - - cubic arc with virtual 'on' point -
-
- - -

- b. Outline descriptor -

- -

A FreeType outline is described through a simple structure:

- -
- - - - - - - - - - - - - - - - - - - - - - - -
- FT_Outline -
- n_points - - the number of points in the outline -
- n_contours - - the number of contours in the outline -
- points - - array of point coordinates -
- contours - - array of contour end indices -
- tags - - array of point flags -
-
- -

Here, points is a pointer to an array of - FT_Vector 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 26.6 fixed float format.

- -

contours 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 contours[0]. The second - contour starts at point contours[0]+1 and ends at - contours[1], etc.

- -

Note that each contour is closed, and that n_points should - be equal to contours[n_contours-1]+1 for a valid outline.

- -

Finally, tags is an array of bytes, used to store each - outline point's tag.

- - - -

- 2. Bounding and control box computations -

- -

A bounding box (also called bbox) 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.

- -

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.

- -

We thus define the control box (also called cbox) - 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.

- -

Unlike the bbox, the cbox is much faster to compute.

- -
- - - - - -
- a glyph with different bbox and cbox - - a glyph with identical bbox and cbox -
-
- -

Control and bounding boxes can be computed automatically through the - functions FT_Get_Outline_CBox() and - FT_Get_Outline_BBox(). The former function is always very - fast, while the latter may 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. - -

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.

- - - -

- 3. Coordinates, scaling and grid-fitting -

- -

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).

- -

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.

- -

The following operations can be used to round vectorial distances in - the 26.6 format to the grid:

- - 
-    round( x )   == ( x + 32 ) & -64
-    floor( x )   ==          x & -64
-    ceiling( x ) == ( x + 63 ) & -64
- -

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:

- -

The scan-line converter draws all the pixels whose centers - fall inside the glyph shape. It can also detect drop-outs, - 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.

- -

This leads to the following computations:

- -
    -
  • -

    compute the bbox

    -
    • -
  • -

    grid-fit the bounding box with the following:

    - - 
    -    xmin = floor( bbox.xMin )
-    xmax = ceiling( bbox.xMax )
-    ymin = floor( bbox.yMin )
-    ymax = ceiling( bbox.yMax )
    -
    • -
  • - return pixel dimensions, i.e. - - 
    -    width = (xmax - xmin)/64
    - - and - - 
    -    height = (ymax - ymin)/64
    -
    • -
- -

By grid-fitting the bounding box, it is guaranteed that all the pixel - centers that are to be drawn, including those coming from drop-out - control, will be within the adjusted box. Then the box's - dimensions in pixels can be computed.

- -

Note also that, when translating a grid-fitted outline, one should - always use integer distances 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 very low - quality bitmaps and pixmaps.

- - -

- -
- - - - - - -
- Previous - - Contents - - Next -
-
- -
-
- - - diff --git a/docs/glyphs/glyphs-7.html b/docs/glyphs/glyphs-7.html deleted file mode 100644 index 381a98d2b..000000000 --- a/docs/glyphs/glyphs-7.html +++ /dev/null @@ -1,356 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- - -
- -
- - - - - - -
- Previous - - Contents - -   -
-
- -

- - - -
-

- VII. FreeType bitmaps -

-
- -

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.

- - - -

- 1. Vectorial versus pixel coordinates -

- -

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).

- -

In the pixel case, as we use the Y upwards convention; - the coordinate [0,0] always refers to the lower left pixel of a - bitmap, while coordinate [width-1, rows-1] to its upper right - pixel.

- -

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.

- -

The pixels themselves are indeed square boxes 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).

- -

This introduces some differences when computing distances. For - example, the length 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.

- -
- bitmap and vector grid -
- - - -

- 2. FreeType bitmap and pixmap descriptor -

- -

A bitmap or pixmap is described through a single structure, called - FT_Bitmap, defined in the file - <freetype/ftimage.h>. It is a simple descriptor whose - fields are:

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- FT_Bitmap -
- rows - - the number of rows, i.e. lines, in the bitmap -
- width - - the number of horizontal pixels in the bitmap -
- pitch - - 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 -
- buffer - - a typeless pointer to the bitmap pixel bufer -
- pixel_mode - - an enumeration used to describe the pixel format of the bitmap; - examples are ft_pixel_mode_mono for 1-bit monochrome - bitmaps and ft_pixel_mode_grays for 8-bit anti-aliased - "gray" values -
- num_grays - - 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. -
-
- - -

Note that the sign of the pitch fields determines whether - the rows in the pixel buffer are stored in ascending or descending - order.

- -

Remember that FreeType uses the Y upwards convention in - the 2D plane, which means that a coordinate of (0,0) always refer to the - lower-left corner of a bitmap.

- -

If the pitch is positive, the rows are stored in decreasing vertical - position; the first bytes of the pixel buffer are part of the - upper bitmap row.

- -

On the opposite, if the pitch is negative, the first bytes of the - pixel buffer are part of the lower bitmap row.

- -

In all cases, one can see the pitch as the byte increment needed to - skip to the next lower scanline in a given bitmap buffer.

- -
- - - - - -
- negative 'pitch' - - positive 'pitch' -
-
- -

The "positive pitch" convention is very often used, though - some systems might need the other.

- - - -

- 3. Converting outlines into bitmaps and pixmaps -

- -

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:

- -
    -
  • -

    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).

    -
    • -
  • -

    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 [w,h] will be mapped to a 2D rectangle window - delimited by (0,0)-(w,h).

    -
    • -
  • -

    When scan-converting the outline, everything that falls within - the bitmap window is rendered, the rest is ignored.

    -
    • - -

    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.

    - -
      -
    • - The first image shows a loaded outline in the 2D plane. -
      • -
    • - The second one shows the target window for a bitmap of arbitrary - dimensions [w,h]. -
      • -
    • - The third one shows the juxtaposition of the outline and window in - the 2D plane. -
      • -
    • - The last image shows what will really be rendered in the bitmap. -
      • -
    - -
    - clipping algorithm -
    -
- -

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.

- -

For example, the correct way of creating a standalone glyph - bitmap is as follows

- -
    -
  • -

    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).

    -
    • -
  • -

    Create the bitmap with the computed dimensions. Don't forget to - fill the pixel buffer with the background color.

    -
    • -
  • -

    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 - (-ROUND(xMin), -ROUND(yMin)).

    -
    • -
  • -

    Call the rendering function (it can be - FT_Outline_Render() for example).

    -
    • -
- -

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.

- -

- -
- - - - - - -
- Previous - - Contents - -   -
-
- -
-
- - - diff --git a/docs/glyphs/grid_1.png b/docs/glyphs/grid_1.png deleted file mode 100644 index f99826bd70d36eabd3d46af577f8eb4f00d2019f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2079 zcmV+)2;ldLP)DeZQ-YZ})EYcDL8#4sO%j z?3>^G=Dm6I=FQygwgM-vv5Jfm5bCp)QnExiYuT148N5R$r|b% zP@1>5Vh5TXH_Y%uy!KMMjCNkWMTZaYQci#NW|W9fuPd3}X?soE`4c4!_}O$hg~Lw7 zX5$g-1DMTaSF(&5O7r$M?cg)|`S*Bdx{Nw%cj#~~Am+3qc}*E5WP;h3P!}14Ns0H0 z-O{Kxk`2?YzS)+t$n^1YBpa5=o4cgxlXUusEpv`W`Fv>|^SsGD0fBT4y-CH14 z+X@XSWM~Q$g@t*74*$atAjF;}L2!701Yw9sy24~LBx_Izf#4MON3kocsCUwwJIn>a zYJB-nHLwmPEQGg3FW4 zd9W3Og)k9-7#(D+LlS~(d|E`c?(H!|lnLZaR|!nzbO2(Uxt7UL=u*wJg_(K7QHOa? z4vzAMk_8$kZ&D!*ntTnA_OFQxL}=&$an}>)vR5J`k)Z!j!0iSSYVW9*GdqOSCn?FY zt{=|ArjDWRPsFVw69x!=>-Bs;JRFt2b^9`nkELrg>Pn6t7@_B%lk4|+9$eK4Jq8H< z_DbD%eUE>3mwVqsrG2)!rXfg%;wFb%GIS9*(N%`#0eb8wK!DIkA2S39vI9<_BQzje zNP?iFafKa0^XmDqg4^PFNeqGh#GN&$kQP>FTr~z(bpx@(gA5U}$x;smd>k{+GyqZ2 z?lK*uVD15B9C=%Imkc8rA~{l(ue zjqWo*3jPWXVprV+@OK*^fj_K5E%n3r_tF6WRD^rY@%Zi&+67;?-N`lm(6l+GuTF3{c>f{6-owhpE`E)5QCbPN>ABi`UFJB8 z9VeV?Y@ajDRqcY1)I(8}Rom3wk{pg3w91)pJ*gbh{)dpvA=GNhYObQ+qLZ;RvUt#H z>|8B=n~R?EK3Cr7%DKwEo>c6#_X^3_X9MnUwI_G%Tt$9! ztfzb?FQ3T^maEi|%!tubH0?LFjiTy|YoSpPOvh6gJ<5{Fb9IC3Dc5Z5OrBeO>YFOR z={~oasx#)Q#<51zTvbedQ_?x(*7PU~XE?nTmM{Cyrqc9S=YVO>F7Pg}`3wyG*}B1H zlN0~7C2W@y`$Y-b<_vwf$L@F}%qw=E1IpT49ZsGdmcVm#5Ol?bc=F%P6nW;ka?pf> z7_s|v0p53C{Z_Q~-{=8<|KfG8|K9)9vIE9NiqD zDI!M}#h&9Tr`G+wFYxM{w5Kz|b)Kf1Ptw4G57Pb%kk>xE7C52V+cxdvz5LG)QeDk6 z+xY4CsS>-8XwCtNKSt6x+Q<_gGvmmeEcGz!JG0v*oem7q&GI9BlRNZerx^!QJk`jy zRKL~{051#K|p;Wr=Sb6Ehr~Nr&6pEy|y3*?h zq+SbSW?r>&nR1k-{r8@Ah1wRscqDdvDE9T#2hrPKYhp|}@;JSD1oO=iF0iHRsc2Vg zmxm5)$-!~c>o|sOj+_g)57kC!;B_AgxS8BOkjn1~l{ux&`5&M&VHxr>;S&G=002ov JPDHLkV1jS(2jl<% diff --git a/docs/glyphs/index.html b/docs/glyphs/index.html deleted file mode 100644 index 8ee2fa515..000000000 --- a/docs/glyphs/index.html +++ /dev/null @@ -1,200 +0,0 @@ - - - - - - FreeType Glyph Conventions - - - - -

- FreeType Glyph Conventions -

- -

- Version 2.1 -

- -

- Copyright 1998-2000 David Turner (david@freetype.org)
- Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- - -
- - -
- -

This document presents the core conventions used within the FreeType - library to manage font and glyph data. It is a must-read for all - developers who need to understand digital typography, especially if you - want to use the FreeType 2 library in your projects.

- - - - - -
-

- Table of Contents -

-
- -
- - -
- -

- I. Basic Typographic Concepts -

-
-

- 1. Font files, format and - information -
- - 2. Character images and mappings -
- - 3. Character and font metrics -
-

-
- -

- II. Glyph outlines -

-
-

- 1. Pixels, points and device - resolutions -
- - 2. Vectorial representation -
- - 3. Hinting and bitmap rendering -
-

-
- -

- III. Glyph metrics -

-
-

- 1. Baseline, pens and layouts -
- - 2. Typographic metrics and - bounding boxes -
- - 3. Bearings and advances -
- - 4. The effects of grid-fitting -
- - 5. Text widths and bounding box -
-

-
- -

- IV. Kerning -

-
-

- 1. Kerning pairs -
- - 2. Applying kerning -
-

-
- -

- V. Text processing -

-
-

- 1. Writing simple text strings -
- - 2. Sub-pixel positioning -
- - 3. Simple kerning -
- - 4. Right-to-left layouts -
- - 5. Vertical layouts -
- - 6. WYSIWYG text layouts -
-

-
- -

- VI. FreeType Outlines -

-
-

- 1. FreeType outline description - and structure -
- - 2. Bounding and control box - computations -
- - 3. Coordinates, scaling, and - grid-fitting -
-

-
- -

- VII. FreeType bitmaps -

-
-

- 1. Vectorial versus pixel - coordinates -
- - 2. FreeType bitmap and pixmap - descriptor -
- - 3. Converting outlines into - bitmaps and pixmaps -
-

-
- -
-
- -
-
- - - diff --git a/docs/glyphs/points_conic.png b/docs/glyphs/points_conic.png deleted file mode 100644 index 80a670f29ad7727e329f9ac8c43a900482d0ba59..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 846 zcmV-U1F`&xP)ZLgdfvOC$GX|g@|BYT*A-}$`Rd2i;;Y{)Q- ze2CFNvq20OLiJ&@QOrj8;X5oFsKIm}u&r!*A{#>9!_4QC)6lAVybKI#a4s5n8$PS+ zDE7_OGn?qmEP-uKQKx~b5ws0h?!mMVHl~UOFmfeCe5N4A4lk4*C{q$gaa9AJJ2-ox zYu`l^DI;h)Z1#X1U2yx!*QIqz=eXmcOKa8s8hgBu*PXiHO@xZJzD~fl<3(;w=y+60 zLrMd;&QbGWO6!zHlumGT;QcaUT168*AxX;v3-8GSw0O(+{>?+zyPhA-boz`(EHPYoH9B9S-WtrYpxEn`w% zl7A&p@&1L>_h94x^m{fMSPq08SCbb8MiA`f;l_xQHwd7Zv zW61tEU}D0qbIis%8zVN>0^x2p7T6dtF<~G74G;u3el>OBLNT=$Uc**Z5f>)lz}1fC zv8IlLPg*A~w<#xw&yABKLK&Y%(-HDZ9Z1jJSw9}Ww?Cd96hFWc#xLY(DxQYN(sP&6 zl01`)&md6-)Wrn>EAlTys5h}f9QR9yO|6_L$1wm^S8oZwP92V_gKh17a`Hxx{6?C- zh9CD;a3&@9#Rj8EMK0tHQ&1eiR$ewUx;oT}gkS?*ZkP!Lo- zAObB_eIXZ2w%=hLkvrX9=^GDHs|Bt0PPYsUc`%-_iN`a?b77L?&0T7hw2$K z8K$N3Sdl+};bc1*>T89AV}+z34%t~pC1KZw5LAseV(oQirnh-)w%PF%xP~&RQLTK@ zxTj>6fTm?qF>UvZVLU$a#i`}l+|DQDy?st(aMR;lecl60q6f;6e|oyv=fWnt$zF&3 zb{#Brds*OoO{OFx{?&@bWrcqD!mq5ErCP;Q@^&F%ylF)S&_x6 z0qmQvKCD8s8@KkA>-Yi|yTW7@w(sT+d<$67yKSRBBmGqzG1>R-3Vb)Ut#AgruC^Ul~!V7jjUD3t6euI2T{LXD73B!n)zQ%Ja>QoNi_F$=(8}4 z%nLi=TUo)y9*9L3p-^1PN-$CpBnY#PuexKgdFNL3K>zVqo>3qC;e&6~-_AYNp;_Db z`K|qkQF|hrvS*1J>>sg@A1R?D^KT#DfByTxS5p7hXTbw+Hi9NA<)hLeB+jDQU-Jz) z7Z#)WBFu%c#lAY3Lo-7B{qUD{gB^$!gi0JsqQ zg+T>KbZ3mk$<*0O7%&`jCX1%th!6=d4@9_4x)C^UWhOAhp7^@lU{4t*vcDWb-TJ zHx&?zKhMLgvzJ_mguP&GDK1DNZaUp*(Sl#C0Ff95bPaGD)*CYvAz~1VE7F{?&LHzc zJj)MM0;`?&d?oPTEMU!;v}(aQ4%GIJjBXy?a{BJ!3l{vAOkmKS8M<;5S}-HGjmYge zDf~L~=*deHW; z_W57hbA&6u$}PcZKAh|h$YO5N5t+;fAAjUeua8usXLq^B23=RiX4dIyr8o)-KQ4>7 zSvNsMh~FM?5yL$e}Bc|GWPuY*O78f7`6`_zQy!@=?#^{F$(htqsGSf2Z0 z{2sU32dmCmTj#x1-Bjcdt82+BVrtiPp?1}{7N1ijRl5ABNlkW1UGbO6v;-V(ht{ts zAR(!8H#(5U%}G7^vB%+FpunbIEW_G3XnJC>gF?!URaxuyQlh1 t4h7>+m7v@eS8^G|{2`xMqW@=|{Q`i}$f$gdMUVgh002ovPDHLkV1mNvu`U1r diff --git a/docs/glyphs/points_segment.png b/docs/glyphs/points_segment.png deleted file mode 100644 index 67f94b592f52d0d10e345be721720f9e7a4499e2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 661 zcmV;G0&4wDb(P!S_m@e_!6+KXNk6}(v}J$S0H1Uyuv)B(>$5bQxk3W9p72V)X&Y3C$+ zsJMrMsOjz=a>zmBRJLX}na!+jcVqL5n^&7^sU?BTn=M7|$SAMUD3YlDU_OZciIm0f`>Vea6-%N_S)`FC zQKkK48pS~C$nE8+M*V0x(|>%eZA8~d^K}PbC)zdG(f~PFiJdv1#Hl!-j|(wCAJbrf zJ|@WkYdd>5ifv$fVWBWr^v=2KGckTzU7kFDeev<^y(`&cMfy%rzO^O=RKX5kcR0kZ z3+=)dqQK4^P~lV(Q6MtFHm2btx`+(0ja%>$T|@@h#_juvE}&w75|2(GazKUWED=o- z|Ib4Dadbi@*g3_S1mCH~s-sR;^|Pm9Tu}}C@|U8}$ICI=kBn;*Hws6_pPcSn48*!U zxA58d@Zi!W)-TMx;9aPfOPr{j=AQX=<0}}-y)VNYA=fFX5z~6qni?TJDqD?^Rbrn% zpU7FVMx0Rhz+YsII9nLlD^227Lh8yaLWb03TZ9a$GO-BRqzY`FkWH#I=Ly*)iaN+q zQX5nb9~l2e%AW7IWSjEq(W}9I^HBBRs5WaoyR))?%^aJsIwOm=XD-70p%f(n;V*& zyNYsih%sT(q|ix|=wuhrJ=?ae+P3XKF%BDYYX1NKZ!XF!1k4NKo-U3d6}R3-a!z`z z!1IRxbiHH$MZ11hMLqV-+a}*sF`W={>e!;Y93_H3Ci9xJMB4v8Ht&!+w~@_(s_qM$ zeBSQ;{))TEWXi_r?eE3%U2g??oG;clQnA^5esaZ|qpM46IrR;XYJS<7bF{m7vtOrq zO7bZuzm(X6|7ZTJ)43OZ;3DgvnL4wyJzh=7xPM6ajq}ZG9F||b?u7T`Y&m)9g2m*S zYj_vfOtj$owWVUIO4760RhQ>PM}E&XKh?hNeS-To&AtC#98>vN_S>bJPrQHnMW)Bs zp0ArN=w#_|QNUs!Yfm=Ujz;SQaW!?{Et^&>(sMZR#x`Q#FOlvu8arDf4QH(=75?5a z_nbg&4sUbLyQ}99Y(IEuxt?{|;Jn(e-!Th@J-eZyn{a4IQ6}k3kcXh ziMy-&4U^v7W40;c&W6_dwq2rPlOC7osa#mDDR$h@hv`t7b+>i0dgzLMMtaP~g|m`9 zE7vH!x-45E^Wc)@o#e7vN4IGx9zS?ZZr>N~mX*b?3b)(p^%s7x7SrfE6S{wzmjB6< zDPFmziCa!>jE~d~xxD>Bn%g?dZmUCond2trY>a**wmbg%v{xXwFRb*%tfy9Gd%}Kw z>Dn!*etQ0N@tMzm{<5ywuDxnNs^a-<_lL| z?eLLo?Y!y-RL2zb=>krf!hIpLRk1lFcRQ z&!ts$oaJ-Z&;BrX^|>>(;`7daEsAXv*}iFu3ge{*`?n^45>$Kr>Lvf_cOqXBuJ>N~ zzTtJxLA|LjeqNJ^{tmdKI;Vst0DIrGod5s; diff --git a/docs/glyphs/twlewis2.png b/docs/glyphs/twlewis2.png deleted file mode 100644 index eb780a28ff749ddc6c936d8bbeb922d49567c0e6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1320 zcmeAS@N?(olHy`uVBq!ia0vp^#XzjW!OXzG_)G98F9QQJLx4|+D^PG0P#yxgxuLna zt0*^z7!xK<3Y|2GPIdv^vuzvw>>|edR8;f-|9_^Q*YdzD@z~SFF{I+w+c3_e#|i>( z_!sZL(Eswi;Ij#gk!36Ayjd1wI8Ct0az=C7g==m91YU3F=aTv@@cqmAeb&v}Gegyu zZ8W(nY%f~7>DBJTi*qBwo0hFkRu=1?=T%p0`sVBX1y3i2_p1s&={?V?xB7R+=ABg$ zf7QkI-r9F|RnN4ai#6_ctd83F{m>MFe_DzWf-0$LGLf^F?+Ht+p0d@w`l^<=oN(=J zp0{0lGV<7-7P8K+yLz`mG!h;?p^nV@10)9aVpTvMm6Sg=GFP^ ztdZLDFCICzh<|xC2b05hqs69iS8ryee?PsD=e%6T2J`E87S1RWe#g*nu=&-h{Kvv^ zTpK^lQ}a^meYJCz^X+Th$+}aN`So9f2wiVwpB!x)QM*HXr846rAsY>=S)!F2dM6Yu zy8Y^n&yvm~7B(e**CM4t#EtE5e82c}n$>=W;%AHgE67wygA$OZtDnm{r-UW|821aj diff --git a/docs/glyphs/up_flow.png b/docs/glyphs/up_flow.png deleted file mode 100644 index 390828bdb70398acdfc0bf7d0a681e16820e727b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2232 zcma)82~bm677Y-V&_)f*G)n-5h#(>{L1f<@2xcGx)o8I98%3Z&=?pu{sv!16HbY=o z6%80okTqcuglU8U2}=wT0*Ij_i-;@<4FP&ScDEzcbl3c^mH>FEM3{*(71B zo(kE25Su86mvod#;`*m$okrLXULSak%xrOf0nR)t{s91E=ut6xSEJ5nG zHI$SrgxSMFOT*fyY&vvi*aNi*@iWZHND@cgsEKWGwx*?yG|s1*7`6z;Mg3$VZLaZy zIM07<)u`2)SJK$B!W%U4d(se5R4JxEzIMl(TT^><;S?+2&1J8I=Igf{(xRg8@c2Vx z(25_&!!|g=XPX-vKQ9Vb(^_vuwvD8AyTlRO_(*4PQZeWOs&@n*q>aMUyt1QP?uW9` z7l_5(@|%5D%{D?F`+JX7v2YmN$&GwJ(mA+(ZB&8Y9Ty#0q*jITmU`=QsNo;$ssecV z=)MFM0X#qj1S}xfO|$=E@F(z$_b;#UR!kos#H#7+XWT}{IQR~4Dx0(3El7@$v`=aT)xeHw%g^$co_@&NuTNvV^#T>do?Stk)Y^j3Bvd`&N3de?!>_@hJ z?%tAp-GV>vTpgti#7`P z*q0|pBW4+{hVfyvM62id{u$iXtF_b$$ZIsOZuu3iMlpNkSJfEX^u{>31`=fPg9iu( z!k|ged9u`QEyZBJ{#I>5h6LG`n5DH}-tj2)v$}sEJ2pBf(;$kOf(**MJwH3tF42aR z-66?8q2uR}RgO#@PCaE^E=NY6=vnfYy`cY-(4S8LtY9|ZxZ(y^h3!N(b`CFJue}OF z_WouIU#9JHj9nodtK80z-C1hgUT&A6^NRABMt|%%yH41)qgY*NaG8mW5T*-thgVt~ z!a;io|0C^p*V5E7QYmPH9#!0?c1(QpM*IhpD(nt-+lJYL%d;aJcb%))*<1Pr0e1a3 zpR~AjwQwY2%zu?`62C8GoW(-{y8b0}g*CQ0{^st5_5kW4k#YEkL3g^<*N9Di$GcLc zAEAWxqKmUzKQp(UGR2!q9J1I#HNiAk59P{h=T2wr?Canp^mIN52B3?w>(NNXr0nU~#kdSej+Iv=kuKLFmLKr?Nr6Pt zva#L}2gm5y)hSjjoP|SNzQMA}DW=(Po!ONP(u>RJdi~v)L};2tD8M zj=~oXz|NU){5?|zHYU7W!^IS8MY*AE0XPfm38NT-qX-V4XW_&!a9?Slq~mnHaTmfU zYCllg9;(|{vY-z5Ju>jg89u+Gwd108F~`WSXIJ15Evl!nkV`oxu}aK!6b;sS2F4xnT>dLztFRqxbZf|676 zx{|6cCPQb@^`QVmE3nbuMp%ysj(aKH>FpPI&vbCY#r#`oAd_1*Rm2VAo7a70Di5P2 zX4xCy_o~4*$+)!1OvcTHLcpBAYYCX#E5NGpu>)~O@FzLwAS}fH2+B`G#YO!12E?

h$v;@PJl`aYQ9&acku7)n3gYFp$jB1-InO^`%1Yo+P|6E&ZB-8)0aB?MRGaYT+cge5)E8MK$ugmjx_u8$^QWm{MS7I diff --git a/docs/image/freetype.jpg b/docs/image/freetype.jpg deleted file mode 100644 index 0c6304fa1cdb4594e8d8a2d1559228fff89608ed..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 10516 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 diff --git a/docs/tutorial/metrics2.png b/docs/tutorial/metrics2.png deleted file mode 100644 index 0b4a66f086134f85c8c710536a21481b23a8d041..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1861 zcmV-L2fFx)P)02XvbSaefwW^{L9a%BK#X=XBTZf77eE;24PIk&DK000KqNkl7%Q6ae5^uN!ZoCH`rUTw!X*vA`4wIjBfERQ0BDg%h<^2)*>SX<7v0Kq@XAXuWAe z@5`d)?jj3Ra03Ma2tI*_yxv#F&^NjDfGW*F- ztA!X{b>-&1y#9KoKv&_@ajAbvEi=@y-N})xGD}xd^|^(K7iPkA)!qGKVP&E#L|47N zFK6zYOh+}|A!miGqW2i}#<2{KN~%0}jBIjctZWU|?kV{Vrs{s>+RtAE4N+UgPaIi2 z&b-!OY_xicCM-2jn2UWAbjO&ZvYF5OJ`7T-qjHnw{N*5}IVw3^9ZUv|bi4I1L4y0; zfU$-CJ{XuA-fIQVaJO9mOa?2}Rq5bK6!Z2hVD>#%=G1wVK%d;UlDJfiGov|_2zKCF zcDt}LSI1QfVD-L%t8@6&Z{oK#@G5r@FZu?aGI)N720n<9dS|;xO4QBQsKJPBDE~b2 z+)+YFgx6z{pwa+uy@sjxF(nXG6CWW1U`nTFjubcrWGgSsIIx$l%v&o!3KLbk`btP8 z*$VzM!=)5@yLQW|qqVh=Mpw`F<$nEm^a7(N26IPG@4FfT^mYy8tHbgomdZ|FxwR(| zV%)Jby#M^-5tb^Cp7yL{=e>7a zxYS=*aAvKJ7Pz{1rEA6VQZ}O^RWw>b>eIfgs#r>ZcdMHp3gei%nacgRY$@{r-!MN6 zl`(Z&I{a4NQfcEUa}_{TA8q_|ENQ7?Q!X0jhv8DE60~+sR2s5bKOX?;5T@FhBN%nr zT6+*wsI6cnltoL~Pa~lt`>gkf0c0USxjM?F(k(dJe5%4y#Vw>BP*ufLuv-PXYVs(< zRB1!o0VUX~&Y_}A)v%OKRpKL14GtAysK^u5R?Qt#;v-P3oY>+}!nPDE?^_(R1K3L2 z2~{zyS<9#sMNXx`n$uz^SR!Pz)Cr903l%J4bOpN|R^J9g!D%a-&r!O9LnNE)ZMuTp z3ZGUQOBIbx*b$b3k6blCnUB3DQg9`d2~cVD`@vLjFqKTe9V_P31u6JPC989033FAz zDs2m`VBm+tg|))f2D!hQu6k|k$PJA=LXEaMv~+xX)O0Mo{&I(Q3CIP?YI-6r&b8s>!8Vj2dkRqpsR9!=-N0>#7}h8MP3_UyNFa;y$Cw z@hGP&=&Q$w9^p||7N!|0iZZ&$So@;iLlMT>7b%gh&LJhx)t3DWjH(1jRjB#ZZ2~=g+trtDBL;tORZL&sE5myNV zFJ;G8F8h?-_YrqKhEDFw{ZjIt2JJHJ(T=)vJ6t+czF5lpR12x1M{SlyYt?C=GLWjc z)uem%_eEbx^c8ZEtCBnAOXI5KfTxnPR*&|h1Ad6_0|0O!qS>ojwCM^}30HELAeR4hpC@Q>7CH!Z#ldXT~@7OPqRnd2e{uo(RG_Q&WoUJ)C z4Mlf`hy?%n&@LrF`A$l9X~cGkMsq!NuXg79A?xjjuh&yLN$DJY-=P9RFm#T?K!I=u zM(9;OgSdwzgQR5WV$ETb-qO%lo zr1D6~5;{vEW_&33=2XE{JwxVM3R#8bb7lDagDRw;vlL=1?lW|jLW=JEt$1k}{HcSXchFf1 zDSDsz`)sw&o{ykCADL0)%C9t++6$h - - - - - FreeType 2 Tutorial - - - - -

- FreeType 2.0 Tutorial
- Step 1 -- simple glyph loading -

- -

- © 2000 David Turner - (david@freetype.org)
- © 2000 The FreeType Development Team - (www.freetype.org) -

- -
- - -
- -
- -

- Introduction -

- -

This is the first part of the FreeType 2 tutorial. It will - teach you to do the following:

- -
    -
  • initialize the library
    • -
  • open a font file by creating a new face object
    • -
  • select a character size in points or in pixels
    • -
  • load a single glyph image and convert it to a bitmap
    • -
  • render a very simple string of text
    • -
  • render a rotated string of text easily
    • -
- -
- -

- 1. Header files -

- -

To include the main FreeType header file, say

- - - 
-    #include <freetype/freetype.h>
- - -

in your application code. Note that other files are available in the - FreeType include directory, most of them being included by - freetype.h and other (internal) files. Some of them will be - described later in this tutorial.

- -
- -

- 2. Initialize the library -

- -

Simply create a variable of type FT_Library named, for - example, library, and call the function - FT_Init_FreeType() as in

- - - 
-    #include <freetype/freetype.h>
-
-    FT_Library  library;
-
-    ...
-
-    {
-      ...
-      error = FT_Init_FreeType( &library );
-      if ( error )
-      {
-        ... an error occurred during library initialization ...
-      }
-    }
- - -

This function is in charge of the following:

- -
    -
  • - Creating a new instance of the FreeType 2 library, and set the - handle library to it. -
    • -
  • - Load each module that FreeType knows about in the library. This - means that by default, your new library object is able to - handle TrueType, Type 1, Windows FON, CID-keyed & OpenType/CFF - fonts gracefully. -
    • -
- -

As you can see, the function returns an error code, like most others - in the FreeType API. An error code of 0 always means that - the operation was successful; otherwise, the value describes the error, - and library is set to NULL.

- -
- -

- 3. Load a font face -

- -

- a. From a font file -

- -

Create a new face object by calling - FT_New_Face(). A face describes a given typeface - and style. For example, "Times New Roman Regular" and "Times New - Roman Italic" correspond to two different faces.

- - - 
-    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
-    }
- - -

As you can certainly imagine, FT_New_Face() opens a font - file, then tries to extract one face from it. Its parameters are

- - - - - - - - - - - - - - - - - - -
- library - -

A handle to the FreeType library instance where the face - object is created

-
- filepathname - -

The font file pathname (a standard C string).

-
- face_index - -

Certain font formats allow several font faces to be embedded - in a single file.

- -

This index tells which face you want to load. An error will - be returned if its value is too large.

- -

Index 0 always work though.

-
- face - -

A pointer to the handle that will be set to describe - the new face object.

- -

It is set to NULL in case of error.

-
- -

To know how many faces a given font file contains, load its first - face (use face_index=0), then check the value of - face->num_faces which indicates how many faces are embedded - in the font file.

- -

- b. From memory -

- -

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 - FT_New_Memory_Face() as in

- - - 
-    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 ) { ... }
- - -

As you can see, FT_New_Memory_Face() 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 - FT_New_Face().

- -

- c. From other sources (compressed files, network, etc.) -

- -

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.

- -

This is done through the FT_Open_Face() 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.

- -

Note that providing a custom stream might also be used to access a - TrueType font embedded in a Postscript Type 42 wrapper.

- -
- -

- 4. Accessing face contents -

- -

A face object models all information that globally describes - the face. Usually, this data can be accessed directly by dereferencing - a handle, like

- - - - - - - - - - - - - - - - - - - - - - -
- face->num_glyphs - -

Gives the number of glyphs available in the font face. - A glyph is simply a character image. It doesn't necessarily - correspond to a character code though.

-
- face->flags - -

A 32-bit integer containing bit flags used to describe some - face properties. For example, the flag - FT_FACE_FLAG_SCALABLE 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 FreeType 2 API Reference.

-
- face->units_per_EM - -

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.

-
- face->num_fixed_sizes - -

This field gives the number of embedded bitmap strikes - in the current face. A strike 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!

-
- face->fixed_sizes - -

This is a pointer to an array of FT_Bitmap_Size - elements. Each FT_Bitmap_Size indicates the horizontal - and vertical pixel sizes for each of the strikes that are - present in the face.

-
- -

For a complete listing of all face properties and fields, please read - the FreeType 2 API Reference.

- -

- -

- 5. Setting the current pixel size -

- -

FreeType 2 uses size objects 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.

- -

When the FT_New_Face() function is called (or one of its - cousins), it automatically creates a new size object for the - returned face. This size object is directly accessible as - face->size.

- -

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.

- -

Before a glyph can be loaded, the size object must be set up. To do - that, simply call FT_Set_Char_Size(). Here is an example where - the character size is set to 16pt for a 300x300 dpi device:

- - - 
-    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      */
- - -

You will notice that

- -
    -
  • - The character width and heights are specified in 1/64th of points. - A point is a physical distance, equaling 1/72th of an inch; - it is not a pixel. -
    • -
  • - Horizontal and vertical device resolutions are expressed in - dots-per-inch, or dpi. 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. -
    • -
  • - A value of 0 for the character width means same as - character height, a value of 0 for the character height - means same as character width. Otherwise, it is possible - to specify different char widths and heights. -
    • -
  • - Using a value of 0 for the horizontal or vertical resolution - means 72 dpi, which is the default. -
    • -
  • - The first argument is a handle to a face object, not a size object. - This behaviour must be seen as a convenience. -
    • -
- -

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 - FT_Set_Pixel_Sizes(), as in

- - - 
-    error = FT_Set_Pixel_Sizes(
-              face,   /* handle to face object */
-              0,      /* pixel_width           */
-              16 );   /* pixel_height          */
- - -

This example will set the character pixel sizes to 16x16 pixels. - As previously, a value of 0 for one of the dimensions means - same as the other.

- -

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 - face->fixed_sizes array.

- -
- -

- 6. Loading a glyph image -

- -

- a. Converting a character code into a glyph index -

- -

Usually, an application wants to load a glyph image based on its - character code, which is a unique value that defines the - character for a given encoding. For example, the character - code 65 in ASCII encoding represents letter `A'.

- -

A face object contains one or more tables, called - charmaps, 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.

- -

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.

- -

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 FT_New_Face(). To convert a - Unicode character code to a font glyph index, we use - FT_Get_Char_Index() as in

- - - 
-    glyph_index = FT_Get_Char_Index( face, charcode );
- - -

This will look up the glyph index corresponding to the given - charcode in the charmap that is currently selected for the - face. - -

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 missing - glyph, which usually is represented as a box or a space.

- -

- b. Loading a glyph from the face -

- -

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 outlines, 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.

- -

The glyph image is always stored in a special object called a - glyph slot. 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 face->glyph.

- -

Loading a glyph image into the slot is performed by calling - FT_Load_Glyph() as in

- - - 
-    error = FT_Load_Glyph(
-              face,          /* handle to face object */
-              glyph_index,   /* glyph index           */
-              load_flags );  /* load flags, see below */
- - -

The load_flags value is a set of bit flags used to - indicate some special operations. The default value - FT_LOAD_DEFAULT is 0.

- -

This function will try to load the corresponding glyph image from - the face. Basically, this means that

- -
    -
  • -

    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 FT_LOAD_NO_BITMAP flag.

    -
    • -
  • -

    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.

    -
    • -
- -

The field glyph->format describes the format used to store - the glyph image in the slot. If it is not - ft_glyph_format_bitmap, it is possible to immedialy convert - it to a bitmap through FT_Render_Glyph(), as in

- - - 
-   error = FT_Render_Glyph(
-             face->glyph,      /* glyph slot  */
-             render_mode );    /* render mode */
- - -

The parameter render_mode specifies how to render the - glyph image. Set it ft_render_mode_normal to render a - high-quality anti-aliased (256 gray levels) bitmap. You can - alternatively use ft_render_mode_mono if you want to generate - a 1-bit monochrome bitmap.

- -

Once you have a bitmapped glyph image, you can access it directly - through glyph->bitmap (a simple bitmap descriptor), and - position it with glyph->bitmap_left and - glyph->bitmap_top.

- -

Note that bitmap_left is the horizontal distance from the - current pen position to the left-most border of the glyph bitmap, - while bitmap_top is the vertical distance from the pen - position (on the baseline) to the top-most border of the glyph bitmap. - It is positive to indicate an upwards distance.

- -

The second part of the tutorial describes the contents of a glyph - slot and how to access specific glyph information (including - metrics).

- -

- c. Using other charmaps -

- -

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 face->charmap. This field - is NULL if no charmap is selected, which typically happens - when you create a new FT_Face object from a font file that - doesn't contain an ASCII, Latin-1, or Unicode charmap (rare - stuff).

- -

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 freetype/freetype.h, - as ft_encoding_big5. In this case, you can simply call - FT_Select_CharMap() as in

- - 
-    error = FT_Select_CharMap(
-              face,                 /* target face object */
-              ft_encoding_big5 );   /* encoding           */
- - -

Another way is to manually parse the list of charmaps for the face; - this is accessible through the fields num_charmaps and - charmaps (notice the final 's') of the face object. As - expected, the first is the number of charmaps in the face, while the - second is a table of pointers to the charmaps embedded in the - face.

- -

Each charmap has a few visible fields used to describe it more - precisely. Mainly, one will look at charmap->platform_id and - charmap->encoding_id which define a pair of values that can - be used to describe the charmap in a rather generic way.

- -

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 <freetype/ttnameid.h> which defines - several helpful constants to deal with them.

- -

Note that some pid/eid pairs are artificial; such values - have been created by FreeType to identify platforms resp. encodings - not covered by the original TrueType specification.

- -

To look up a specific encoding you need to find a corresponding - value pair in the specification, then look for it in the - charmaps 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:

- - - 
-    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 ) { ... }
- - -

Once a charmap has been selected, either through - FT_Select_CharMap() or FT_Set_CharMap(), it is used - by all subsequent calls to FT_Get_Char_Index().

- -

- d. Glyph transformations -

- -

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.

- -

To do that, simply call FT_Set_Transform(), as in

- - - 
-    error = FT_Set_Transform(
-              face,       /* target face object    */
-              &matrix,    /* pointer to 2x2 matrix */
-              &delta );   /* pointer to 2d vector  */
- - -

This function will set the current transformation for a given face - object. Its second parameter is a pointer to an FT_Matrix - structure that describes a 2x2 affine matrix. The third - parameter is a pointer to an FT_Vector structure that - describes a simple 2d vector that is used to translate the glyph - image after the 2x2 transformation.

- -

Note that the matrix pointer can be set to NULL, in which - case the identity transformation will be used. Coefficients of the - matrix are otherwise in 16.16 fixed float units.

- -

The vector pointer can also be set to NULL 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).

- -

The transformation is applied to every glyph that is loaded - through FT_Load_Glyph() and is completely independent of - any hinting process. 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).

- -

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 - FT_Set_Transform(). This is explained in details in a later - section of this tutorial.

- -

Note also that loading a glyph bitmap with a non-identity - transformation will produce an error.

- -
- -

- 7. Simple text rendering -

- -

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

- -

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.

- -

- a. basic code -

- -

The following code performs our simple text rendering with the - functions previously described.

- - - 
-    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 */
-    }
- - -

This code needs a few explanations:

- -
    -
  • - We define a handle named slot that points to the face - object's glyph slot. (The type FT_GlyphSlot is a - pointer.) This is a convenience to avoid using - face->glyph->XXX every time. -
    • -
  • - We increment the pen position with the vector - slot->advance, which corresponds to the glyph's - advance width (also known as its escapement). - The advance vector is expressed in 1/64th of pixels, and is - truncated to integer pixels on each iteration. -
    • -
  • - The function my_draw_bitmap() 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 - FT_Bitmap descriptor and the position of its top-left - corner as arguments. -
    • -
  • - The value of slot->bitmap_top is positive for an - upwards vertical distance. Assuming that the coordinates - taken by my_draw_bitmap() use the opposite convention - (increasing Y corresponds to downwards scanlines), we substract it - to pen_y instead of adding it. -
    • -
- -

b. refined code

- -

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.

- - - 
-    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;
-    }
- - -

We have reduced the size of our code, but it does exactly the same - thing.

- -
    -
  • -

    We use the function FT_Load_Char() instead of - FT_Load_Glyph(). As you probably imagine, it is - equivalent to calling FT_Get_Char_Index() followed by - FT_Get_Load_Glyph().

    -
    • -
  • -

    We do not use FT_LOAD_DEFAULT for the loading mode but - the bit flag FT_LOAD_RENDER. It indicates that the glyph - image must be immediately converted to an anti-aliased bitmap. - This is of course a shortcut that avoids calling - FT_Render_Glyph() explicitly but is strictly - equivalent.

    - -

    Note that you can also specify that you want a monochrome - bitmap by using the FT_LOAD_MONOCHROME load flag - instead.

    -
    • -
- -

c. more advanced rendering

- -

We now render transformed text (for example through a rotation). - To do that we use FT_Set_Transform():

- - - 
-    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;
-    }
- - -

Notes:

- -
    -
  • - We now use a vector of type FT_Vector to store the pen - position, with coordinates expressed as 1/64th of pixels, hence a - multiplication. The position is expressed in cartesian space. -
    • -
  • - 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. -
    • -
  • - 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). -
    • -
  • - The advance width is always returned transformed, which is why it - can be directly added to the current pen position. Note that it - is not rounded this time. -
    • -
- -

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).

- -

It has, however, a few shortcomings that we will explain, and - solve, in the next part of this tutorial.

- -
- -

- Conclusion -

- -

In this first section, you have learned the basics of FreeType 2 - as well as sufficient knowledge how to render rotated text.

- -

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.

- -

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.

- -
-
- - - diff --git a/docs/tutorial/step2.html b/docs/tutorial/step2.html deleted file mode 100644 index f47264467..000000000 --- a/docs/tutorial/step2.html +++ /dev/null @@ -1,1607 +0,0 @@ - - - - - - FreeType 2 Tutorial - - - - -

- FreeType 2.0 Tutorial
- Step 2 -- managing glyphs -

- -

- © 2000 David Turner - (david@freetype.org)
- © 2000 The FreeType Development Team - (www.freetype.org) -

- -
- - -
- -
- -

- Introduction -

- -

This is the second part of the FreeType 2 tutorial. It will teach - you the following:

- -
    -
  • how to retrieve glyph metrics
    • -
  • how to easily manage glyph images
    • -
  • how to retrieve global metrics (including kerning)
    • -
  • how to render a simple string of text, with kerning
    • -
  • how to render a centered string of text (with kerning)
    • -
  • how to render a transformed string of text (with centering)
    • -
  • finally, how to access metrics in design font units if needed, - and how to scale them to device space
    • -
- -
- -

- 1. Glyph metrics -

- -

Glyph metrics are, as their name suggests, certain distances - associated to each glyph in order to describe how to use it to layout - text.

- -

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).

- -

Note that only a few font formats provide vertical metrics. You can - test wether a given face object contains them by using the macro - FT_HAS_VERTICAL(face), which is true if vertical metrics are - available.

- -

Individual glyph metrics can be accessed by first loading the glyph - in a face's glyph slot, then using the face->glyph->metrics - structure. This will be described later; for now, we observe that it - contains the following fields:

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- width - - This is the width of the glyph image's bounding box. It is - independent of the layout direction. -
- height - - This is the height of the glyph image's bounding box. It is - independent of the layout direction. -
- horiBearingX - - For horizontal text layouts, this is the horizontal - distance from the current cursor position to the left-most border of - the glyph image's bounding box. -
- horiBearingY - - For horizontal text layouts, 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. -
- horiAdvance - - For horizontal text layouts, this is the horizontal - distance used to increment the pen position when the glyph is drawn - as part of a string of text. -
- vertBearingX - - For vertical text layouts, this is the horizontal distance - from the current cursor position to the left-most border of the - glyph image's bounding box. -
- vertBearingY - - For vertical text layouts, 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. -
- vertAdvance - - For vertical text layouts, this is the vertical distance - used to increment the pen position when the glyph is drawn as part - of a string of text. -
-
- -

As not all fonts do contain vertical metrics, the values of - vertBearingX, vertBearingY, and vertAdvance - should not be considered reliable if FT_HAS_VERTICAL(face) is - false.

- -

The following graphics illustrate the metrics more clearly. First - horizontal metrics, where the baseline is the horizontal axis:

- -
- horizontal metrics layout -
- -

For vertical text layouts, the baseline is vertical and is the - vertical axis:

- -
- vertical metrics layout -
- -

The metrics found in face->glyph->metrics are normally - expressed in 26.6 pixel format (i.e 1/64th of pixels), unless you use - the FT_LOAD_NO_SCALE flag when calling FT_Load_Glyph() - or FT_Load_Char(). In that case, the metrics will be expressed - in original font units.

- -

The glyph slot object has a few other interesting fields that will - ease a developer's work. You can access them through - face->glyph->???:

- -
- - - - - - - - - - - - - -
- advance - - This field is an FT_Vector which holds the transformed - advance value for the glyph. This is useful if you are using a - transformation through FT_Set_Transform(), 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 - FT_LOAD_VERTICAL when loading the glyph image; it will then - be (0,metrics.vertAdvance). -
- linearHoriAdvance - - This field contains the linearly-scaled value of the glyph's - horizontal advance width. Indeed, the value of - metrics.horiAdvance 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. linearHoriAdvance 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. -
- linearVertAdvance - - This is the same thing as linearHoriAdvance for the glyph's - vertical advance height. Its value is only reliable if the font - face contains vertical metrics. -
-
- -
- -

- 2. Managing glyph images -

- -

The glyph image that is loaded in a glyph slot can be converted into - a bitmap, either by using FT_LOAD_RENDER when loading it, or by - calling FT_Render_Glyph() afterwards. Each time you load a new - glyph image, the previous one is erased from the glyph slot.

- -

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.

- -

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 ftglyph.h header file:

- - - 
-    #include <freetype/ftglyph.h>
- - -

We will now explain how to use the functions defined in this - file.

- -

- a. Extracting the glyph image -

- -

You can extract a single glyph image very easily. Here some code - that shows how to do it.

- - - 
-    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 ) { .... }
- - -

As can be seen, we have

- -
    -
  • - created a variable, named glyph, of type - FT_Glyph. This is a handle (pointer) to an individual - glyph image, -
    • -
  • - loaded the glyph image normally in the face's glyph slot. We did - not use FT_LOAD_RENDER because we want to grab a scalable - glyph image in order to transform it later, -
    • -
  • - copied the glyph image from the slot into a new FT_Glyph - object by calling FT_Get_Glyph(). This function returns - an error code and sets glyph. -
    • -
- -

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.

- -

You can access the field glyph->format if you want to know - exactly how the glyph is modeled and stored. A new glyph object can - be destroyed with a call to FT_Done_Glyph().

- -

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 - glyph->advance.

- -

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 - FT_Done_FreeType() to do all the clean-up.

- -

- b. Transforming & copying the glyph image -

- -

If the glyph image is scalable (i.e., if glyph->format is - not ft_glyph_format_bitmap), it is possible to transform the - image anytime by a call to FT_Glyph_Transform().

- -

You can also copy a single glyph image with - FT_Glyph_Copy(). Here some example code:

- - - 
-    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 );
- - -

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.

- -

- c. Measuring the glyph image -

- -

You can also retrieve the control (bounding) box of any glyph image - (scalable or not), using the FT_Glyph_Get_CBox() - function:

- - - 
-    FT_BBox  bbox;
-
-
-    ...
-    FT_Glyph_Get_CBox( glyph, bbox_mode, &bbox );
- - -

Coordinates are relative to the glyph origin, i.e. (0,0), using the - Y upwards convention. This function takes a special argument, - bbox_mode, to indicate how box coordinates are expressed. If - bbox_mode is set to ft_glyph_bbox_subpixels, the - coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels). - -

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

- - - 
-    width  = bbox.xMax - bbox.xMin;
-    height = bbox.yMax - bbox.yMin;
- - -

Note also that for 26.6 coordinates, if - ft_glyph_bbox_gridfit is set in bbox_mode, the - coordinates will also be grid-fitted, which corresponds to

- - - 
-    bbox.xMin = FLOOR(bbox.xMin)
-    bbox.yMin = FLOOR(bbox.yMin)
-    bbox.xMax = CEILING(bbox.xMax)
-    bbox.yMax = CEILING(bbox.yMax)
- - -

The default value for bbox_mode is - ft_glyph_bbox_pixels (i.e. integer, grid-fitted pixel - coordinates). Please check the API reference of - FT_Glyph_Get_CBox() for other possible values.

- -

- d. Converting the glyph image to a bitmap -

- -

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 FT_Glyph_To_Bitmap() function:

- - - 
-    FT_Vector  origin;
-
-
-    origin.x = 32;   /* 1/2 pixel in 26.6 format */
-    origin.y = 0;
-
-    error = FT_Glyph_To_Bitmap( &glyph,
-                                render_mode,
-                                &origin,
-                                1 );  /* destroy orig. image == true */
- - -

Some details on this function's parameters:

- -
    -
  • - The first parameter is the address of the source glyph's - handle. When the function is called, it reads it to access - the source glyph object. After the call, the handle will point to - a new glyph object that contains the rendered bitmap. -
    • -
  • - The second parameter is a standard render mode that is used to - specify what kind of bitmap we want. It can be - ft_render_mode_default for an 8-bit anti-aliased pixmap, - or ft_render_mode_mono for a 1-bit monochrome bitmap. -
    • -
  • - 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. -
    • -
  • - 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). -
    • -
- -

The new glyph object always contains a bitmap (when no error is - returned), and you must typecast its handle to the - FT_BitmapGlyph type in order to access its contents. This - type is a sort of subclass of FT_Glyph that contains - additional fields:

- -
- - - - - - - - - - - - - -
- left - - Just like the bitmap_left 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. -
- top - - Just like the bitmap_top 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. -
- bitmap - - This is a bitmap descriptor for the glyph object, just like the - bitmap field in a glyph slot. -
-
- -
- -

- 3. Global glyph metrics -

- -

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 font units for scalable formats.

- -

- a. Design global metrics -

- -

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 FT_Face handle.

- -

However, you need to check that the font face's format is scalable - before using them. This can be done with the macro - FT_IS_SCALABLE(face) which returns true if we have a scalable - format.

- -

In this case, you can access the global design metrics as

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- units_per_EM - - 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. -
- global_bbox - - 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. -
- ascender - - The ascender is the vertical distance from the horizontal baseline - to the height of the highest character in a font face. - Unfortunately, font formats define the ascender - differently. 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 global_bbox.yMax. -
- descender - - The descender is the vertical distance from the horizontal - baseline to the depth of the lowest character in a font face. - Unfortunately, font formats define the descender - differently. 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 global_bbox.yMin. - This field is usually negative. -
- text_height - - 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. -
- max_advance_width - - 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. It doesn't correspond to - the maximum glyph image width! -
- max_advance_height - - Same as max_advance_width but for vertical text layout. - It is only available in fonts providing vertical glyph metrics. -
- underline_position - - 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). -
- underline_thickness - - When displaying or rendering underlined text, this value - corresponds to the vertical thickness of the underline. -
-
- -

Notice how, unfortunately, the values of the ascender and the - descender are not reliable (due to various discrepancies in font - formats).

- -

- b. Scaled global metrics -

- -

Each size object also contains scaled versions of some of the - global metrics described above. They can be accessed directly through - the face->size->metrics structure.

- -

Note that these values correspond to scaled versions of the design - global metrics, with no rounding/grid-fitting performed. 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.

- -
- - - - - - - - - - - - - - - - - -
- ascender - - This is the scaled version of the original design ascender. -
- descender - - This is the scaled version of the original design descender. -
- height - - The scaled version of the original design text height. This is - probably the only field you should really use in this structure. -
- max_advance - - This is the scaled version of the original design max advance. -
-
- -

Note that the face->size->metrics structure contains other - fields that are used to scale design coordinates to device space. - They are described below.

- -

- c. Kerning -

- -

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".

- -

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.

- -

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 .pfa or .pfb, and where kerning - metrics can be found in an additional file with extension - .afm or .pfm.

- -

FreeType 2 allows you to deal with this by providing the - FT_Attach_File() and FT_Attach_Stream() 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:

- - - 
-    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 ..
-    }
- - -

Note that FT_Attach_Stream() is similar to - FT_Attach_File() except that it doesn't take a C string - to name the extra file, but a FT_Stream handle. Also, - reading a metrics file is in no way mandatory.

- -

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.

- -

FreeType 2 allows you to retrieve the kerning information - between two glyphs through the FT_Get_Kerning() function, - whose interface looks like

- - - 
-    FT_Vector  kerning;
-
-
-    ...
-    error = FT_Get_Kerning(
-              face,              /* handle to face object */
-              left,              /* left glyph index      */
-              right,             /* right glyph index     */
-              kerning_mode,      /* kerning mode          */
-              &kerning );        /* target vector         */
- - -

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 kerning mode, and - a pointer to a destination vector that receives the corresponding - distances.

- -

The kerning mode is very similar to bbox_mode described in - a previous part. It is an enumeration value that indicates how the - kerning distances are expressed in the target vector.

- -

The default value ft_kerning_mode_default (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.

- -

The value ft_kerning_mode_unfitted 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.

- -

Finally, the value ft_kerning_mode_unscaled 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.

- -

Note that the "left" and "right" positions correspond to the - visual order of the glyphs in the string of text. This is - important for bidirectional text, or when writing right-to-left - text.

- -
- -

- 4. Simple text rendering: kerning + centering -

- -

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.

- -

- a. Kerning support -

- -

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

- - - 
-    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;
-    }
- - -

We are done. Notice that

- -
    -
  • - As kerning is determined from glyph indices, we need to - explicitly convert our character code into a glyph index, then - later call FT_Load_Glyph() instead of - FT_Load_Char(). -
    • -
  • - We use a Boolean named use_kerning which is set with the - result of the macro FT_HAS_KERNING(face). It is - certainly faster not to call FT_Get_Kerning() if we - know that the font face does not contain kerning information. -
    • -
  • - We move the position of the pen before a new glyph is - drawn. -
    • -
  • - We did initialize the variable previous with the - value 0, which always correspond to the missing - glyph (also called .notdef in the PostScript world). - There is never any kerning distance associated with this glyph. -
    • -
  • - We do not check the error code returned by - FT_Get_Kerning(). This is because the function always - set delta to (0,0) when an error occurs. -
    • -
- -

- b. Centering -

- -

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.

- -

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.

- -

We start by storing individual glyph images, as well as their - position on the baseline. This can be done with code like

- - - 
-    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++;
-    }
- - -

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.

- -

Note also that pen_x contains the total advance for the - string of text. We can now compute the bounding box of the text - string with a simple function like

- - - 
-    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;
-    }
- - -

The resulting bounding box dimensions can then be used to compute - the final pen position before rendering the string as in:

- - - 
-    /* 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 );
-      }
-    }
- - -

Some remarks:

- -
    -
  • - The pen position is expressed in the cartesian space (i.e. - Y upwards). -
    • -
  • - We call FT_Glyph_To_Bitmap() with the destroy - parameter set to 0 (false), in order to avoid destroying the - original glyph image. The new glyph bitmap is accessed through - image after the call and is typecast to an - FT_BitmapGlyph. -
    • -
  • - We use translation when calling FT_Glyph_To_Bitmap(). - This ensures that the left and top fields of the - bitmap glyph object are already set to the correct pixel - coordinates in the cartesian space. -
    • -
  • - Of course, we still need to convert pixel coordinates from - cartesian to device space before rendering, hence the - my_target_height - bitmap->top in the call to - my_draw_bitmap(). -
    • -
- -

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.

- -
- -

- 5. Advanced text rendering: transformation + centering + kerning -

- -

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:

- -

- a. packing & translating glyphs -

- -

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:

- - - 
-    typedef struct  TGlyph_
-    {
-      FT_UInt    index;    /* glyph index                  */
-      FT_Vector  pos;      /* glyph origin on the baseline */
-      FT_Glyph   image;    /* glyph image                  */
-
-     } TGlyph, *PGlyph;
- - -

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:

- - - 
-    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;
- - -

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:

- - - 
-    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;
-    }
- - -

compute_string_bbox() can now compute the bounding box of - a transformed glyph string. For example, we can do something - like

- - - 
-    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 );
- - -

- b. Rendering a transformed glyph sequence -

- -

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:

- - - 
-    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 );
-      }
-    }
- - -

There are a few changes compared to the previous version of this - code:

- -
    -
  • - We keep the original glyph images untouched, by transforming a - copy. -
    • -
  • - We perform clipping computations in order to avoid rendering & - drawing glyphs that are not within our target surface. -
    • -
  • - We always destroy the copy when calling - FT_Glyph_To_Bitmap() 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 - FT_Done_Glyph() is only called within the compound - statement). -
    • -
  • - The translation of the glyph sequence to the start pen position is - integrated in the call to FT_Glyph_Transform() intead of - FT_Glyph_To_Bitmap(). -
    • -
- -

It is possible to call this function several times to render the - string with different angles, or even change the way start - is computed in order to move it to a different place.

- -

This code is the basis of the FreeType 2 demonstration program - named ftstring.c. It could be easily extended to perform - advanced text layout or word-wrapping in the first part, without - changing the second one.

- -

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).

- -
- -

- 6. Accessing metrics in design font units and scaling them -

- -

Scalable font formats usually store a single vectorial image, called - an outline, for each glyph in a face. Each outline is defined - in an abstract grid called the design space, with coordinates - expressed in nominal font units. When a glyph image is loaded, - the font driver usually scales the outline to device space according to - the current character pixel size found in a FT_Size object. - The driver may also modify the scaled outline in order to significantly - improve its appearance on a pixel-based surface (a process known as - hinting or grid-fitting).

- -

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:

- -
    -
  • -

    to perform "true" WYSIWYG text layout.

    -
    • -
  • -

    to access font data for conversion or analysis purposes

    -
    • -
- -

- a. Scaling distances to device space -

- -

Design coordinates are scaled to device space using a simple - scaling transformation whose coefficients are computed with the help - of the character pixel size:

- - - 
-    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
- - -

Here, the value EM_size 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 face->units_per_EM. You should - check that a font face contains scalable glyph images by using the - FT_IS_SCALABLE(face) macro, which returns true when the font - is scalable.

- -

When you call the function FT_Set_Pixel_Sizes(), you are - specifying the value of pixel_size_x and - pixel_size_y; FreeType will then immediately compute the - values of x_scale and y_scale.

- -

When you call the function FT_Set_Char_Size(), 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.

- -

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 face->size->metrics structure. These fields are:

- -
- - - - - - - - - - - - - - - - - -
- x_ppem - - This is the size in integer pixels of the EM square, which also is - the horizontal character pixel size, called - pixel_size_x in the above example. x_ppem means - "x pixels per EM". -
- y_ppem - - This is the size in integer pixels of the EM square, which also is - the vertical character pixel size, called - pixel_size_y in the above example. y_ppem means - "y pixels per EM". -
- x_scale - - 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. -
- y_scale - - 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. -
-
- -

You can scale a distance expressed in font units to 26.6 pixels - directly with the help of the FT_MulFix() function, as - in:

- - - 
-    /* 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 );
- - -

However, you can also scale the value directly with more accuracy - by using doubles and the equations:

- - - 
-    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;
- - -

- b. Accessing design metrics (glyph & global) -

- -

You can access glyph metrics in font units by specifying the - FT_LOAD_NO_SCALE bit flag in FT_Load_Glyph() or - FT_Load_Char(). The metrics returned in - face->glyph->metrics will then all be in font units.

- -

Unscaled kerning data can be retrieved using the - ft_kerning_mode_unscaled mode.

- -

Finally, a few global metrics are available directly in font units - as fields of the FT_Face handle, as described in - section 3 of this tutorial part.

- -
- -

- Conclusion -

- -

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).

- -

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.

- -

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).

-
-
- - -