+
+ +
+
+
+
+
+ +
+ #include <freetype.h>
+
+ FT_Library library;
+
+ ....
+
+ {
+ ..
+ error = FT_Init_FreeType( &library );
+ if (error) { .. an error occured during library initialisation .. }
+ }
+
+ + 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 succesful; otherwise, the value describes the error, and library + is set to NULL. +
+ +
+
+
+ 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, read or simply that it is broken..
+ }
+
+
+ As you certainly imagine, FT_New_Face opens a font file then + tries to extract one face from it. Its parameters are :
+
| library + | handle to the FreeType library instance where the face object is + created + + |
| filepathname + | the font file pathname (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 known how many faces a given font file contains, simply load its + first face (use face_index=0), then see the value of + face->num_faces which indicates how many faces are embedded in + the font file. +
+ +
+
+
+ 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 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 than + FT_New_Face. +
+ +
+ Basically, one has to set up a FT_Stream object, according to + the rules defined in the document named + FreeType 2 System Interface, then pass it to the function + FT_Open_Face as in: +
+
+
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
+
+ error = FT_Init_FreeType( &library );
+ if (error) { ..... }
+
+ ... set up stream object, with handle "stream" ...
+
+ error = FT_Open_Face( library,
+ stream, /* handle to stream objects */
+ 0, /* face_index */
+ &face );
+ if (error) { ... }
+
+
+ custom implementations of FT_Stream are great to provide advanced + features like automatic support of compressed files, network transparency, + using UTF-16 file pathnames, etc.. +
+
+
+ +
+
| 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 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 simply 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 embedded bitmap strikes ! + + |
| face−>fixed_sizes + | this is a pointer to an array of FT_Bitmap_Size element. + 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. +
+
+
+ When a new face object is created, its size object defaults to the + character size of 10 pixels (both horizontall and vertically) for + scalable formats. For fixed-sizes formats, the size is more or less + undefined, which is why you must set it before trying to load a + glyph. +
+ To do that, simply call FT_Set_Char_Size. Here's an example + where the character size is set to 16 pts 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'll notice that:
+
+ +
+ +
+ +
+
+ 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. +
+ +
+ 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, bwerk..). 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'll describe later how to look for specific charmaps in a face. For + now, we'll 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 the glyph index corresponding to the given charcode + in the charmap that is currently selected for the face. If charmap is + selected, the function simply returns the charcode. +
+ 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 usually is + represented as a box or a space. +
+
+ +
+ The glyph image is always stored in a special object called a + glyph slot. As it names 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 + 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. The function performs the following :
+
+ +
+ +
+ There are a few others FT_LOAD_xxx flags defined. For more + details see the FreeType 2 API Reference. +
+ +
+ The field face−>num_charmaps and + face−>charmaps (notice the 's') can be used by + client applications to look at what charmaps are available in a given + face. +
+ face−charmaps is an array of pointers + to the face−>num_charmaps charmaps contained in the + font face. +
+ Each charmap has a few visible fields used to describe it in more details. + For example, charmap->encoding is an enumeration type + that describes the charmap with FreeType codes. One can also look at + charmap->platform_id and + charmap->encoding_id for more exotic needs. +
+ Here's an example code that looks for a chinese Big5 charmap then + selects it via FT_Set_CharMap: +
+
+ FT_CharMap found = 0;
+ FT_CharMap charmap;
+ int n;
+
+ for ( n = 0; n < face->num_charmaps; n++ )
+ {
+ charmap = face>charmaps[n];
+ if (charmap->encoding == ft_encoding_big5)
+ {
+ found = charmap;
+ break;
+ }
+ }
+
+ if (!found) { ... }
+
+ /* now, select the charmap for the face object */
+ error = FT_Set_CharMap( face, found );
+ if (error) { .... }
+
+
+ One might now call FT_Get_Char_Index with Big5 character codes + to retrieve glyph indices. +
+
+
+ +
+
+ {
+ FT_GlyphSlot glyph;
+
+ .... load glyph ...
+
+ glyph = face->glyph; /* shortcut to glyph data */
+
+ .... access glyph data as glyph->xxxx
+ }
+
+
+ For example, one can access the following fields: +
+
| glyph−>format + | Indicates the type of the loaded glyph image. Can be either + ft_glyph_format_bitmap, ft_glyph_format_outline + or other values. + + |
| glyph−>metrics + | A simple structure used to hold the glyph image's metrics. Note + that all distances are expressed in 1/64th of pixels ! + See the API reference or User Guide for a description of the + FT_Glyph_Metrics structure. + + |
| glyph−>bitmap + | When the glyph slot contains a bitmap, a simple FT_Bitmap + that describes it. See the API reference or user guide for a + description of the FT_Bitmap structure. + + |
| glyph−>outline + | When the glyph slot contains a scalable outline, this structure + describes it. See the definition of the FT_Outline + structure. + |
+
+ On the other hand, when the image is a scalable outline, or something else, + FreeType provides a function to convert the glyph image into a + pre-existing bitmap that you'll handle to it, named + FT_Get_Glyph_Bitmap. Here's a simple example code + that renders an outline into a monochrome bitmap : +
+
+ {
+ FT_GlyphSlot glyph;
+
+ .... load glyph ...
+
+ glyph = face->glyph; /* shortcut to glyph data */
+ if (glyph->format == ft_glyph_format_outline )
+ {
+ FT_Bitmap bit;
+
+ /* set-up a bitmap descriptor for our target bitmap */
+ bit.rows = bitmap_height;
+ bit.width = bitmap_width;
+ bit.pitch = bitmap_row_bytes;
+ bit.pixel_mode = ft_pixel_mode_mono; /* render into a mono bitmap */
+ bit.buffer = bitmap_buffer;
+
+ /* render the outline directly into the bitmap */
+ error = FT_Get_Glyph_Bitmap( face, &bit );
+ if (error) { ... }
+ }
+ }
+
+
+ You should note that FT_Get_Glyph_Bitmap doesn't create the + bitmap. It only needs a descriptor, of type FT_Bitmap, + and writes directly into it. +
+ Note that the FreeType scan-converter for outlines can also generate + anti-aliased glyph bitmaps with 128 level of grays. For now, it is + restricted to rendering to 8-bit gray-level bitmaps, though this may + change in the future. Here's some code to do just that: +
+
+ {
+ FT_GlyphSlot glyph;
+
+ .... load glyph ...
+
+ glyph = face->glyph; /* shortcut to glyph data */
+ if (glyph->format == ft_glyph_format_outline )
+ {
+ FT_Bitmap bit;
+
+ /* set-up a bitmap descriptor for our target bitmap */
+ bit.rows = bitmap_height;
+ bit.width = bitmap_width;
+ bit.pitch = bitmap_row_bytes;
+ bit.pixel_mode = ft_pixel_mode_gray; /* 8-bit gray-level bitmap */
+ bit.grays = 128; /* MUST be 128 for now */
+ bit.buffer = bitmap_buffer;
+
+ /* clean the bitmap - IMPORTANT */
+ memset( bit.buffer, 0, bit.rows*bit.pitch );
+
+ /* render the outline directly into the bitmap */
+ error = FT_Get_Glyph_Bitmap( face, &bit );
+ if (error) { ... }
+ }
+ }
+
+
+ You'll notice that :
+
+ +
+ +
+ +
+