A face object also holds a handle to a size object in its - face->size field. The size object is used to model - all information for the face that is relative to a given character - 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.
+ +NOTA BENE: 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 fuctions.
+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.
+ character size of 10 pixels (both horizontally 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 is an - example where the character size is set to 16pt for a 300x300 dpi - device:
+ example where the character size is set to 16pt for a 300x300 dpi + device:
@@ -351,12 +363,15 @@
The character width and heights are specified in 1/64th of - points.
+ points. A point is a physical distance, equaling 1/72th + of an inch, it's not a pixel..
The 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.
+ 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
@@ -368,6 +383,10 @@
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. That's normal, and must be seen as a convenience.
+This function computes the character pixel size that corresponds to @@ -475,45 +494,62 @@
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:
- + FT_LOAD_DEFAULT is 0. + +This function will try to load the corresponding glyph image + from the face. Basically, this means that:
+If there is a bitmap for the corresponding glyph and size, load - it in the glyph slot, unless the FT_LOAD_NO_BITMAP flag - is set. This is even true for scalable formats (embedded - bitmaps are favored over outlines as they usually correspond to - higher-quality images of the same glyph).
-If there is a glyph image in another format (e.g. a vectorial - outline), load it in the glyph slot. Then, scale it to the - current size, unless the FT_LOAD_NO_SCALE flag is - set.
-If the glyph image was loaded and scaled, try to grid-fit it - (which dramatically improves its quality) unless the flag - FT_LOAD_NO_HINTING is set.
-If the glyph image is scalable, transform it through the - current transform (which can be set with - FT_Set_Transform()).
-Finally, if the FT_LOAD_RENDER flag is set, convert - the glyph image into a bitmap. By default, this means a 1-bit - monochrome bitmap, unless FT_LOAD_ANTI_ALIAS is set, - in which case an 8-bit 256-gray-levels anti-aliased bitmap is - generated.
+If a bitmap is found for the corresponding glyph and pixel + size, it will in the slot (embedded bitmaps are always + favored over native image formats, because we assume that + they are higher-quality versions of the same image. This + can be ignored 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 + Type1.
The field glyph->format describe 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:
-There are a few others FT_LOAD_xxx flags defined. For - more details see the FreeType 2 API - Reference.
+ ++ 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 0 to render + a monochrome bitmap, or to ft_render_mode_antialias to + generate a high-quality (256 gray levels) anti-aliased bitmap + from the glyph image.
+ +Once you have a bitmap 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.
+ +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 next section will detail the content of a glyph slot and + how to access specific glyph information (including metrics).
The fields face->num_charmaps and - face->charmaps (notice the `s') can be used by client - applications to check which 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.
+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 <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 '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.
+ +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.
-Each charmap has a few visible fields used to describe it in more - detail. 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 Big 5 charmap, - then selects it via FT_Set_CharMap():
+Each value pair corresponds to a given encoding. For example, + the pair (3,1) corresponds to Unicode. Their list is + defined in the TrueType specification but you can also use the + file <freetype/ftnameid.h> which defines several + helpful constants to deal with them..
+To look for 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 some encoding correspond to several + values pair (yes it's a real mess, but blame Apple and Microsoft + on such stupidity..). Here's some code to do it:
+
FT_CharMap found = 0;
@@ -554,7 +611,8 @@
for ( n = 0; n < face->num_charmaps; n++ )
{
charmap = face->charmaps[n];
- if ( charmap->encoding == ft_encoding_big5 )
+ if ( charmap->platform_id == my_platform_id &&
+ charmap->encoding_id == my_encoding_id )
{
found = charmap;
break;
@@ -568,9 +626,47 @@
if ( error ) { ... }
- One might now call FT_Get_Char_Index() with Big 5 - character codes to retrieve glyph indices.
+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().
+ +It is possible to specify an affine transformation to be applied + to glyph images when they're 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 transform for a given face + object. Its second parameter is a pointer to a simple + FT_Matrix structure that describes a 2x2 affine matrix. + The third parameter is a pointer to a FT_Vector structure + that describe a simple 2d vector.
+ +Note that the matrix pointer can be set to NULL, (in which case + the identity transform will be used). Coefficients of the matrix + are in 16.16 fixed float units.
+ +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).
+ +NOTA BENE: The transform is applied every glyph that is loaded + through FT_Load_Glyph. Note that loading a glyph bitmap + with a non-trivial transform will produce an error..
+