原文鏈接：http://www.freetype.org/freetype2/docs/tutorial/step1.html
翻譯人員：gogoliu
| 英文 | 中文 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| FreeType 2 Tutorial
Step 1 — simple glyph loading |
FreeType 2 教程
第一步 －－ 簡易的字形裝載 |
||||||||||||||||||||
| Introduction | 介紹 | ||||||||||||||||||||
This is the first section of the FreeType 2 tutorial. It will teach you how to:
|
這是“FreeType2 教程”的第一部分。它將教會你如何：
|
||||||||||||||||||||
| 1. Header files | 1、頭文件 | ||||||||||||||||||||
The following are instructions required to compile an application that uses the FreeType 2 library. Please read them carefully; we have changed a few things since the last release!
#include <ft2build.h>
#include FT_FREETYPE_H
|
下面的內容是編譯一個使用了FreeType2庫的應用程序所需要的指令。請謹慎閱讀，自最近一次版本更新後我們已經更改了少許東西。
#include <ft2build.h> #include FT_FREETYPE_H
|
||||||||||||||||||||
The use of macros in #include statements is ANSI-compliant. It is used for several reasons:
|
#include語句中宏的用法是服從ANSI的。這有幾個原因：
|
||||||||||||||||||||
NOTE: Starting with FreeType 2.1.6, the old header file inclusion scheme is no longer supported. This means that you now get an error if you do something like the following:
#include <freetype/freetype.h> #include <freetype/ftglyph.h> ... |
注意：從FreeType 2.1.6開始，舊式的頭文件包含模式將不會再被支持。這意味着現在如果你做了象下面那樣的事情，你將得到一個錯誤：
#include <freetype/freetype.h> #include <freetype/ftglyph.h> ... |
||||||||||||||||||||
| 2. Initialize the library | 2、初始化庫 | ||||||||||||||||||||
Simply create a variable of type FT_Library named, for example, library, and call the function FT_Init_FreeType as in
#include <ft2build.h>
#include FT_FREETYPE_H
FT_Library library;
...
error = FT_Init_FreeType( &library );
if ( error )
{
... an error occurred during library initialization ...
}
|
簡單地創建一個FT_Library類型的變量，例如library，然後象下面那樣調用函數FT_Init_FreeType：
#include <ft2build.h>
#include FT_FREETYPE_H
FT_Library library;
...
error = FT_Init_FreeType( &library );
if ( error )
{
... 在初始化庫時發生了一個錯誤 ...
}
|
||||||||||||||||||||
This function is in charge of the following:
|
這個函數負責下面的事情：
|
||||||||||||||||||||
| 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. | 就像你所看到的，這個函數返回一個錯誤代碼，如同FreeType API的大部分其他函數一樣。值爲0的錯誤代碼始終意味着操作成功了，否則，返回值指示錯誤，library設爲NULL。 | ||||||||||||||||||||
| 3. Load a font face | 3、裝載一個字體face | ||||||||||||||||||||
| a. From a font file | a. 從一個字體文件裝載 | ||||||||||||||||||||
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 simply that it is broken...
}
|
應用程序通過調用FT_New_Face創建一個新的face對象。一個face對象描述了一個特定的字樣和風格。例如，’Times New Roman Regular’和’Times New Roman Italic’對應兩個不同的face。
FT_Library library; /* 庫的句柄 */
FT_Face face; /* face對象的句柄 */
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 )
{
... 可以打開和讀這個文件，但不支持它的字體格式
}
else if ( error )
{
... 其它的錯誤碼意味着這個字體文件不能打開和讀，
... 或者簡單的說它損壞了 ...
}
|
||||||||||||||||||||
As you can certainly imagine, FT_New_Face opens a font file, then tries to extract one face from it. Its parameters are
|
就如你所想到的，FT_NEW_Face打開一個字體文件，然後設法從中提取一個face。它的參數爲：
|
||||||||||||||||||||
| To know how many faces a given font file contains, simply load its first face (this is, face_index should be set to zero), then check the value of face->num_faces which indicates how many faces are embedded in the font file. | 要知道一個字體文件包含多少個face，只要簡單地裝載它的第一個face(把face_index設置爲0)，face->num_faces的值就指示出了有多少個face嵌入在該字體文件中。 | ||||||||||||||||||||
| b. From memory | b. 從內存裝載 | ||||||||||||||||||||
In the case where you have already loaded the font file into 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 ) { ... }
|
如果你已經把字體文件裝載到內存，你可以簡單地使用FT_New_Memory_Face爲它新建一個face對象，如下所示：
FT_Library library; /* 庫的句柄 */
FT_Face face; /* face對象的句柄 */
error = FT_Init_FreeType( &library );
if ( error ) { ... }
error = FT_New_Memory_Face( library,
buffer, /* 緩存的第一個字節 */
size, /* 緩存的大小（以字節表示） */
0, /* face索引 (face_index) */
&face );
if ( error ) { ... }
|
||||||||||||||||||||
| As you can see, FT_New_Memory_Face simply 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. | 如你所看到的，FT_New_Memory_Face簡單地用字體文件緩存的指針和它的大小（以字節計算）代替文件路徑。除此之外，它與FT_New_Face的語義一致。 | ||||||||||||||||||||
| c. From other sources (compressed files, network, etc.) | c. 從其他來源裝載（壓縮文件，網絡，等） | ||||||||||||||||||||
| There are cases where using a file pathname or preloading the file into memory is simply not sufficient. With FreeType 2, it is possible to provide your own implementation of i/o routines. | 使用文件路徑或者預裝載文件到內存是簡單的，但還不足夠。FreeType 2可以支持通過你自己實現的I/O程序來裝載文件。 | ||||||||||||||||||||
| 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 reference manual in order to learn how to use it. | 這是通過FT_Open_Face函數來完成的。FT_Open_Face可以實現使用一個自定義的輸入流，選擇一個特定的驅動器來打開，乃至當創建該對象時傳遞外部參數給字體驅動器。我們建議你查閱“FreeType 2參考手冊”，學習如何使用它。 | ||||||||||||||||||||
| 4. Accessing face content | 4、訪問face內容 | ||||||||||||||||||||
| A face object models all information that globally describes the face. Usually, this data can be accessed directly by dereferencing a handle, like in face−>num_glyphs. | 一個face對象包含該face的全部全局描述信息。通常的，這些數據可以通過分別查詢句柄來直接訪問，例如face->num_glyphs。 | ||||||||||||||||||||
The complete list of available fields in in the FT_FaceRec structure description. However, we describe here a few of them in more details:
|
FT_FaceRec結構描述包含了可用字段的完整列表。我們在這裏詳細描述其中的某些：
|
||||||||||||||||||||
| 5. Setting the current pixel size | 5、設置當前象素尺寸 | ||||||||||||||||||||
| 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. | 對於特定face中與字符大小相關的信息，FreeType 2使用size對象來構造。例如，當字符大小爲12點時，使用一個size對象以1/64象素爲單位保存某些規格（如ascender或者文字高度）的值。 | ||||||||||||||||||||
| 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. | 當FT_New_Face或它的親戚被調用，它會自動在face中新建一個size對象，並返回。該size對象可以通過face->size直接訪問。 | ||||||||||||||||||||
| NOTE: 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 decided to simplify the API for the most common use (i.e., one size per face) while keeping this feature available through additional functions. | 注意：一個face對象可以同時處理一個或多個size對象，但只有很少程序員需要用到這個功能，因而，我們決定簡化該API（例如，每個face對象只擁有一個size對象），但是這個特性我們仍然通過附加的函數提供。 | ||||||||||||||||||||
When a new face object is created, all elements are set to 0 during initialization. To populate the structure with sensible values, simply call FT_Set_Char_Size. Here is an example where the character size is set to 16pt for a 300×300dpi 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 */
|
當一個新的face對象建立時，所有成員都在初始化階段0設爲0。調用FT_Set_Char_Size對這個結構進行賦值。這裏有一個例子，它在一個300x300dpi設備上把字符大小設置爲16pt。
error = FT_Set_Char_Size( face, /* face對象的句柄 */
0, /* 以1/64點爲單位的字符寬度 */
16*64, /* 以1/64點爲單位的字符高度 */
300, /* 設備水平分辨率 */
300 ); /* 設備垂直分辨率 */
|
||||||||||||||||||||
Some notes:
|
注意：
|
||||||||||||||||||||
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 */
|
這個函數計算對應字符寬度、高度和設備分辨率的字符象素大小。然而，如果你想自己指定象素大小，你可以簡單地調用FT_Set_Pixel_Sizes，就像這樣：
error = FT_Set_Pixel_Sizes( face, /* face對象句柄 */
0, /* 象素寬度 */
16 ); /* 象素高度 */
|
||||||||||||||||||||
| This example will set the character pixel sizes to 16×16 pixels. As previously, a value of 0 for one of the dimensions means ‘same as the other’. | 這個例子把字符象素設置爲16x16象素。如前所說的，尺寸中的任一個爲0意味着“與另一個尺寸值相等”。 | ||||||||||||||||||||
| 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. | 注意這兩個函數都返回錯誤碼。通常，錯誤會發生在嘗試對定長字體格式（如FNT或PCF）設置不在 face->fixed_size 數組中的象素尺寸值。 | ||||||||||||||||||||
| 6. Loading a glyph image | 6、裝載一個字形圖像 | ||||||||||||||||||||
| a. Converting a character code into a glyph index | a. 把一個字符碼轉換爲一個字形索引 | ||||||||||||||||||||
| 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 represents the 'A' in ASCII encoding. | 通常，一個應用程序想通過字符碼來裝載它的字形圖像。字符碼是一個特定編碼中代表該字符的數值。例如，字符碼64代表了ASCII編碼中的'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). Note also that a given charmap might not map to all the glyphs present in the font. | 一個face對象包含一個或多個字符表(charmap)，字符表是用來轉換字符碼到字形索引的。例如，很多TrueType字體包含兩個字符表，一個用來轉換Unicode字符碼到字形索引，另一個用來轉換Apple Roman編碼到字形索引。這樣的字體既可以用在Windows（使用Unicode）和Macintosh（使用Apple Roman）。同時要注意，一個特定的字符表可能沒有覆蓋完字體裏面的全部字形。 | ||||||||||||||||||||
| By default, when a new face object is created, it selects a Unicode charmap. FreeType tries to emulate a Unicode charmap if the font doesn't contain such a charmap, based on glyph names. Note that it is possible that the emulation misses glyphs if glyph names are non-standard. For some fonts, including symbol fonts and (older) fonts for Asian scripts, no Unicode emulation is possible at all. | 當新建一個face對象時，它默認選擇Unicode字符表。如果字體沒包含Unicode字符表，FreeType會嘗試在字形名的基礎上模擬一個。注意，如果字形名是不標準的那麼模擬的字符表有可能遺漏某些字形。對於某些字體，包括符號字體和舊的亞洲手寫字體，Unicode模擬是不可能的。 | ||||||||||||||||||||
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 a call to 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 ); |
我們將在稍後敘述如何尋找face中特定的字符表。現在我們假設face包含至少一個Unicode字符表，並且在調用FT_New_Face時已經被選中。我們使用FT_Get_Char_Index把一個Unicode字符碼轉換爲字形索引，如下所示：
glyph_index = FT_Get_Char_Index( face, charcode ); |
||||||||||||||||||||
| This will look the glyph index corresponding to the given charcode in the charmap that is currently selected for the face. If no charmap was selected, the function simply returns the charcode. | 這個函數會在face裏被選中的字符表中查找與給出的字符碼對應的字形索引。如果沒有字符表被選中，這個函數簡單的返回字符碼。 | ||||||||||||||||||||
| Note that this is one of the rare FreeType functions that do not return an error code. However, when a given character code has no glyph image in the face, the value 0 is returned. By convention, it always correspond to a special glyph image called the missing glyph, which is commonly displayed as a box or a space. | 注意，這個函數是FreeType中罕有的不返回錯誤碼的函數中的一個。然而，當一個特定的字符碼在face中沒有字形圖像，函數返回0。按照約定，它對應一個特殊的字形圖像――缺失字形，通常會顯示一個框或一個空格。 | ||||||||||||||||||||
| b. Loading a glyph from the face | b. 從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 — but this format is not supported). Fortunately, FreeType 2 is flexible enough to support any kind of glyph format through a simple API. | 一旦你獲得了字形索引，你便可以裝載對應的字形圖像。在不同的字體中字形圖像存儲爲不同的格式。對於固定尺寸字體格式，如FNT或者PCF，每一個圖像都是一個位圖。對於可伸縮字體格式，如TrueType或者Type1，使用名爲輪廓(outlines)的矢量形狀來描述每一個字形。一些字體格式可能有更特殊的途徑來表示字形（如MetaFont――但這個格式不被支持）。幸運的，FreeType2有足夠的靈活性，可以通過一個簡單的API支持任何類型的字形格式。 | ||||||||||||||||||||
| The glyph image is always stored in a special object called a glyph slot. As its name suggests, a glyph slot is simply 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. Its fields are explained by the FT_GlyphSlotRec structure documentation. | 字形圖像存儲在一個特別的對象――字形槽(glyph slot)中。就如其名所暗示的，一個字形槽只是一個簡單的容器，它一次只能容納一個字形圖像，可以是位圖，可以是輪廓，或者其他。每一個face對象都有一個字形槽對象，可以通過face->glyph來訪問。它的字段在FT_GlyphSlotRec結構的文檔中解釋了。 | ||||||||||||||||||||
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. |
通過調用FT_Load_Glyph來裝載一個字形圖像到字形槽中，如下：
error = FT_Load_Glyph( face, /* face對象的句柄 */
glyph_index, /* 字形索引 */
load_flags ); /* 裝載標誌，參考下面 */
load_flags的值是位標誌集合，是用來指示某些特殊操作的。其默認值是FT_LOAD_DEFAULT即0。 |
||||||||||||||||||||
This function will try to load the corresponding glyph image from the face:
|
這個函數會設法從face中裝載對應的字形圖像：
|
||||||||||||||||||||
The field face−>glyph−>format describes the format used to store the glyph image in the slot. If it is not FT_GLYPH_FORMAT_BITMAP, one can immediately 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 is a set of bit flags used to specify how to render the glyph image. Set it to FT_RENDER_MODE_NORMAL to render a high-quality anti-aliased (256 gray levels) bitmap, as this is the default. You can alternatively use FT_RENDER_MODE_MONO if you want to generate a 1-bit monochrome bitmap. |
字段face->glyph->format描述了字形槽中存儲的字形圖像的格式。如果它的值不是FT_GLYPH_FORMAT_BITMAP，你可以通過FT_Render_Glyph把它直接轉換爲一個位圖。如下：
error = FT_Render_Glyph( face->glyph, /* 字形槽 */
render_mode ); /* 渲染模式 */
render_mode參數是一個位標誌集合，用來指示如何渲染字形圖像。把它設爲FT_RENDER_MODE_NORMAL渲染出一個高質量的抗鋸齒(256級灰度)位圖。這是默認情況，如果你想生成黑白位圖，可以使用FT_RENDER_MODE_MONO標誌。 |
||||||||||||||||||||
| Once you have a bitmapped glyph image, you can access it directly through glyph->bitmap (a simple bitmap descriptor), and position it through glyph->bitmap_left and glyph->bitmap_top. | 一旦你生成了一個字形圖像的位圖，你可以通過glyph->bitmap(一個簡單的位圖描述符)直接訪問，同時用glyph->bitmap_left和glyph->bitmap_top來指定起始位置。 | ||||||||||||||||||||
| Note that bitmap_left is the horizontal distance from the current pen position to the leftmost border of the glyph bitmap, while bitmap_top is the vertical distance from the pen position (on the baseline) to the topmost border of the glyph bitmap. It is positive to indicate an upwards distance. | 要注意，bitmap_left是從字形位圖當前筆位置到最左邊界的水平距離，而bitmap_top是從筆位置（位於基線）到最高邊界得垂直距離。他麼是正數，指示一個向上的距離。 | ||||||||||||||||||||
| The next section will give more details on the contents of a glyph slot and how to access specific glyph information (including metrics). | 下一部分將給出字形槽內容的更多細節，以及如何訪問特定的字形信息（包括度量）。 | ||||||||||||||||||||
| c. Using other charmaps | c. 使用其他字符表 | ||||||||||||||||||||
| As said before, when a new face object is created, it will look for a Unicode charmap and select it. The currently selected charmap is accessed via face->charmap. This field is NULL when no charmap is selected, which typically happens when you create a new FT_Face object from a font file that doesn't contain a Unicode charmap (which is rather infrequent today). | 如前面所說的，當一個新face對象創建時，它會尋找一個Unicode字符表並且選擇它。當前被選中的字符表可以通過face->charmap 訪問。當沒有字符表被選中時，該字段爲NULL。這種情況在你從一個不含Unicode字符表的字體文件（這種文件現在非常罕見）創建一個新的 FT_Face對象時發生。 | ||||||||||||||||||||
There are two ways to select a different charmap with FreeType 2. The easiest is when the encoding you need already has a corresponding enumeration defined in FT_FREETYPE_H, for example 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 */
|
有兩種途徑可以在FreeType 2中選擇不同的字符表。最輕鬆的途徑是你所需的編碼已經有對應的枚舉定義在FT_FREETYPE_H中，例如FT_ENCODING_BIG5。在這種情況下，你可以簡單地調用FT_Select_CharMap，如下：
error = FT_Select_CharMap( face, /* 目標face對象 */
FT_ENCODING_BIG5 ); /* 編碼 */
|
||||||||||||||||||||
| 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 ‘s’) of the face object. As you could expect, 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. | 另一種途徑是手動爲face解析字符表。這通過face對象的字段num_charmaps和charmaps(注意這是複數)來訪問。如你想到的，前者是face中的字符表的數目，後者是一個嵌入在face中的指向字符表的指針表(a table of pointers to the charmaps)。 | ||||||||||||||||||||
| 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 that define a pair of values that can be used to describe the charmap in a rather generic way. | 每一個字符表有一些可見的字段，用來更精確地描述它，主要用到的字段是charmap->platform_id和charmap->encoding_id。這兩者定義了一個值組合，以更普通的形式用來描述該字符表。 | ||||||||||||||||||||
| Each value pair corresponds to a given encoding. For example, the pair (3,1) corresponds to Unicode. The list is defined in the TrueType specification but you can also use the file FT_TRUETYPE_IDS_H which defines several helpful constants to deal with them. | 每一個值組合對應一個特定的編碼。例如組合(3,1)對應Unicode。組合列表定義在TrueType規範中，但你也可以使用文件FT_TRUETYPE_IDS_H來處理它們，該文件定義了幾個有用的常數。 | ||||||||||||||||||||
To select a specific encoding, you need to find a corresponding value pair in the specification, then look for it in the charmaps list. Don't forget that there are encodings which correspond to several value pairs due to historical reasons. 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 ) { ... }
|
要選擇一個具體的編碼，你需要在規範中找到一個對應的值組合，然後在字符表列表中尋找它。別忘記，由於歷史的原因，某些編碼會對應幾個值組合。這裏是一些代碼：
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 ) { ... }
/* 現在，選擇face對象的字符表 */
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. | 一旦某個字符表被選中，無論通過FT_Select_CharMap還是通過FT_Set_CharMap，它都會在後面的FT_Get_Char_Index調用使用。 | ||||||||||||||||||||
| d. Glyph transformations | d. 字形變換 | ||||||||||||||||||||
| 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 */
|
簡單地調用FT_Set_Transform來完成這個工作，如下：
error = FT_Set_Transform( face, /* 目標face對象 */
&matrix, /* 指向2x2矩陣的指針 */
&delta ); /* 指向2維矢量的指針 */
|
||||||||||||||||||||
| This function will set the current transform for a given face object. Its second parameter is a pointer to a simple FT_Matrix structure that describes a 2×2 affine matrix. The third parameter is a pointer to a FT_Vector structure that describes a simple two-dimensional vector that is used to translate the glyph image after the 2×2 transformation. | 這個函數將對指定的face對象設置變換。它的第二個參數是一個指向FT_Matrix結構的指針。該結構描述了一個2x2仿射矩陣。第三個參數是一個指向FT_Vector結構的指針。該結構描述了一個簡單的二維矢量。該矢量用來在2x2變換後對字形圖像平移。 | ||||||||||||||||||||
| Note that the matrix pointer can be set to NULL, in which case the identity transform will be used. Coefficients of the matrix are otherwise in 16.16 fixed float units. | 注意，矩陣指針可以設置爲NULL，在這種情況下將進行恆等變換。矩陣的係數是16.16形式的固定浮點單位。 | ||||||||||||||||||||
| The vector pointer can also be set to NULL (in which case a delta of (0,0) will be used). The vector coordinates are expressed in 1/64th of a pixel (also known as 26.6 fixed floats). | 矢量指針也可以設置爲NULL，在這種情況下將使用(0, 0)的delta。矢量座標以一個象素的1/64爲單位表示（即通常所說的26.6固定浮點格式）。 | ||||||||||||||||||||
| NOTE: 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 transform, because the hints will have been computed differently (except you have disabled hints). | 注意：變換將適用於使用FT_Load_Glyph裝載的全部字形，並且完全獨立於任何hinting處理。這意味着你對一個12象素的字形進行2倍放大變換不會得到與24象素字形相同的結果（除非你禁止hints）。 | ||||||||||||||||||||
| If you ever need to use a non-orthogonal transformation with optimal hints, you first have 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. | 如果你需要使用非正交變換和最佳hints，你首先必須把你的變換分解爲一個伸縮部分和一個旋轉/剪切部分。使用伸縮部分來計算一個新的字符象素大小，然後使用旋轉/剪切部分來調用FT_Set_Transform。這在本教程的後面部分有詳細解釋。 | ||||||||||||||||||||
| Loading a glyph bitmap with a non-identity transformation works; the transformation is ignored in this case. | 同時要注意，對一個字形位圖進行非同一性變換將產生錯誤。 | ||||||||||||||||||||
| 7. Simple text rendering | 7、簡單的文字渲染 | ||||||||||||||||||||
| 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 | 現在我們將給出一個非常簡單的例子程序，該例子程序渲染一個8位Latin-1文本字符串，並且假定face包含一個Unicode字符表。 | ||||||||||||||||||||
|
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. |
該程序的思想是建立一個循環，在該循環的每一次迭代中裝載一個字形圖像，把它轉換爲一個抗鋸齒位圖，把它繪製到目標表面(surface)上，然後增加當前筆的位置。 | ||||||||||||||||||||
| a. Basic code | a. 基本代碼 | ||||||||||||||||||||
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 */
}
|
下面的代碼完成我們上面提到的簡單文本渲染和其他功能。
FT_GlyphSlot slot = face->glyph; /* 一個小捷徑 */
int pen_x, pen_y, n;
... 初始化庫 ...
... 創建face對象 ...
... 設置字符尺寸 ...
pen_x = 300;
pen_y = 200;
for ( n = 0; n < num_chars; n++ )
{
FT_UInt glyph_index;
/* 從字符碼檢索字形索引 */
glyph_index = FT_Get_Char_Index( face, text[n] );
/* 裝載字形圖像到字形槽（將會抹掉先前的字形圖像） */
error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT );
if ( error )
continue; /* 忽略錯誤 */
/* 轉換爲一個抗鋸齒位圖 */
error = FT_Render_Glyph( face->glyph, FT_RENDER_MODE_NORMAL );
if ( error )
continue;
/* 現在，繪製到我們的目標表面(surface) */
my_draw_bitmap( &slot->bitmap,
pen_x + slot->bitmap_left,
pen_y - slot->bitmap_top );
/* 增加筆位置 */
pen_x += slot->advance.x >> 6;
pen_y += slot->advance.y >> 6; /* 現在是沒用的 */
}
|
||||||||||||||||||||
This code needs a few explanations:
|
這個代碼需要一些解釋：
|
||||||||||||||||||||
| b. Refined code | b. 精練的代碼 | ||||||||||||||||||||
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 are 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;
}
|
下面的代碼是上面例子程序的精練版本。它使用了FreeType 2中我們還沒有介紹的特性和函數，我們將在下面解釋：
FT_GlyphSlot slot = face->glyph; /* 一個小捷徑 */
FT_UInt glyph_index;
int pen_x, pen_y, n;
... 初始化庫 ...
... 創建face對象 ...
... 設置字符尺寸 ...
pen_x = 300;
pen_y = 200;
for ( n = 0; n < num_chars; n++ )
{
/* 裝載字形圖像到字形槽（將會抹掉先前的字形圖像） */
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
if ( error )
continue; /* 忽略錯誤 */
/* 現在，繪製到我們的目標表面(surface) */
my_draw_bitmap( &slot->bitmap,
pen_x + slot->bitmap_left,
pen_y - slot->bitmap_top );
/* 增加筆位置 */
pen_x += slot->advance.x >> 6;
}
|
||||||||||||||||||||
We have reduced the size of our code, but it does exactly the same thing:
|
我們簡化了代碼的長度，但它完成相同的工作：
|
||||||||||||||||||||
| c. More advanced rendering | c. 更高級的渲染 | ||||||||||||||||||||
Let us try to render transformed text now (for example through a rotation). We can do this using FT_Set_Transform. Here is how to do it:
FT_GlyphSlot slot;
FT_Matrix matrix; /* transformation matrix */
FT_UInt glyph_index;
FT_Vector pen; /* untransformed origin */
int n;
... initialize library ...
... create face object ...
... set character size ...
slot = face->glyph; /* a small shortcut */
/* 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 */
/* start at (300,200) */
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;
}
|
現在，讓我們來嘗試渲染變換文字（例如通過一個環）。我們可以用FT_Set_Transform來完成。這裏是示例代碼：
FT_GlyphSlot slot;
FT_Matrix matrix; /* 變換矩陣 */
FT_UInt glyph_index;
FT_Vector pen; /* 非變換原點 */
int n;
... 初始化庫 ...
... 創建face對象 ...
... 設置字符尺寸 ...
slot = face->glyph; /* 一個小捷徑 */
/* 準備矩陣 */
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 );
/* 26.6 笛卡兒空間座標中筆的位置，以(300, 200)爲起始 */
pen.x = 300 * 64;
pen.y = ( my_target_height - 200 ) * 64;
for ( n = 0; n < num_chars; n++ )
{
/* 設置變換 */
FT_Set_Transform( face, &matrix, &pen );
/* 裝載字形圖像到字形槽（將會抹掉先前的字形圖像） */
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
if ( error )
continue; /* 忽略錯誤 */
/* 現在，繪製到我們的目標表面（變換位置） */
my_draw_bitmap( &slot->bitmap,
slot->bitmap_left,
my_target_height - slot->bitmap_top );
/* 增加筆位置 */
pen.x += slot->advance.x;
pen.y += slot->advance.y;
}
|
||||||||||||||||||||
Some remarks:
|
一些說明：
|
||||||||||||||||||||
| A complete source code example can be found here. | 一個例子完整的源代碼可以在這裏找到。 | ||||||||||||||||||||
| 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 transform 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. | 在這個部分，你已經學習了FreeType2的基礎以及渲染旋轉文字的充分知識。 | ||||||||||||||||||||
| The next section will dive into more details of the API in order to let you access glyph metrics and images directly, as well as how to deal with scaling, hinting, kerning, etc. | 下一部分將深入瞭解FreeType 2 API更詳細的資料，它可以讓你直接訪問字形度量標準和字形圖像，還能讓你學習到如何處理縮放、hinting、字距調整，等等。 | ||||||||||||||||||||
| The third section will discuss issues like modules, caching and a few other advanced topics like how to use multiple size objects with a single face. [This part hasn't been written yet.] | 第三部分將討論模塊、緩存和其他高級主題，如如何在一個face中使用多個尺寸對象。【這部分還沒有編寫】 | ||||||||||||||||||||
| Last update: 11-May-2006 | 最後更新：2006年5月11日 |