| <!doctype html public "-//w3c//dtd html 4.0 transitional//en" |
| "http://www.w3.org/TR/REC-html40/loose.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=iso-8859-1"> |
| <meta name="Author" |
| content="David Turner"> |
| <title>FreeType 2 Tutorial</title> |
| </head> |
| |
| <body text="#000000" |
| bgcolor="#FFFFFF" |
| link="#0000EF" |
| vlink="#51188E" |
| alink="#FF0000"> |
| |
| <h1 align=center> |
| FreeType 2.0 Tutorial<br> |
| Step 2 -- managing glyphs |
| </h1> |
| |
| <h3 align=center> |
| © 2000 David Turner |
| (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br> |
| © 2000 The FreeType Development Team |
| (<a href="http://www.freetype.org">www.freetype.org</a>) |
| </h3> |
| |
| <center> |
| <table width="75%"> |
| <tr><td> |
| |
| <hr> |
| |
| <h2> |
| Introduction |
| </h2> |
| |
| <p>This is the second part of the FreeType 2 tutorial. It will teach |
| you the following:</p> |
| |
| <ul> |
| <li>how to retrieve glyph metrics</li> |
| <li>how to easily manage glyph images</li> |
| <li>how to retrieve global metrics (including kerning)</li> |
| <li>how to render a simple string of text, with kerning</li> |
| <li>how to render a centered string of text (with kerning)</li> |
| <li>how to render a transformed string of text (with centering)</li> |
| <li>finally, how to access metrics in design font units if needed, |
| and how to scale them to device space</li> |
| </ul> |
| |
| <hr> |
| |
| <h3> |
| 1. Glyph metrics |
| </h3> |
| |
| <p>Glyph metrics are, as their name suggests, certain distances |
| associated to each glyph in order to describe how to use it to layout |
| text.</p> |
| |
| <p>There are usually two sets of metrics for a single glyph: those used |
| to layout the glyph in horizontal text layouts (like Latin, Cyrillic, |
| Arabic, Hebrew, etc.), and those used to layout the glyph in vertical |
| text layouts (like some layouts of Chinese, Japanese, Korean, and |
| others).</p> |
| |
| <p>Note that only a few font formats provide vertical metrics. You can |
| test wether a given face object contains them by using the macro |
| <tt>FT_HAS_VERTICAL(face)</tt>, which is true if vertical metrics are |
| available.</p> |
| |
| <p>Individual glyph metrics can be accessed by first loading the glyph |
| in a face's glyph slot, then using the <tt>face->glyph->metrics</tt> |
| structure. This will be described later; for now, we observe that it |
| contains the following fields:</p> |
| |
| <center> |
| <table width="90%" cellpadding=5> |
| <tr valign=top> |
| <td> |
| <tt>width</tt> |
| </td> |
| <td> |
| This is the width of the glyph image's bounding box. It is |
| independent of the layout direction. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>height</tt> |
| </td> |
| <td> |
| This is the height of the glyph image's bounding box. It is |
| independent of the layout direction. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>horiBearingX</tt> |
| </td> |
| <td> |
| For <em>horizontal text layouts</em>, this is the horizontal |
| distance from the current cursor position to the left-most border of |
| the glyph image's bounding box. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>horiBearingY</tt> |
| </td> |
| <td> |
| For <em>horizontal text layouts</em>, this is the vertical distance |
| from the current cursor position (on the baseline) to the top-most |
| border of the glyph image's bounding box. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>horiAdvance</tt> |
| </td> |
| <td> |
| For <em>horizontal text layouts</em>, this is the horizontal |
| distance used to increment the pen position when the glyph is drawn |
| as part of a string of text. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>vertBearingX</tt> |
| </td> |
| <td> |
| For <em>vertical text layouts</em>, this is the horizontal distance |
| from the current cursor position to the left-most border of the |
| glyph image's bounding box. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>vertBearingY</tt> |
| </td> |
| <td> |
| For <em>vertical text layouts</em>, this is the vertical distance |
| from the current cursor position (on the baseline) to the top-most |
| border of the glyph image's bounding box. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>vertAdvance</tt> |
| </td> |
| <td> |
| For <em>vertical text layouts</em>, this is the vertical distance |
| used to increment the pen position when the glyph is drawn as part |
| of a string of text. |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <p><em>As not all fonts do contain vertical metrics, the values of |
| <tt>vertBearingX</tt>, <tt>vertBearingY</tt>, and <tt>vertAdvance</tt> |
| should not be considered reliable if <tt>FT_HAS_VERTICAL(face)</tt> is |
| false.</em></p> |
| |
| <p>The following graphics illustrate the metrics more clearly. First |
| horizontal metrics, where the baseline is the horizontal axis:</p> |
| |
| <center> |
| <img src="metrics.png" |
| alt="horizontal metrics layout" |
| width=388 height=253> |
| </center> |
| |
| <p>For vertical text layouts, the baseline is vertical and is the |
| vertical axis:</p> |
| |
| <center> |
| <img src="metrics2.png" |
| alt="vertical metrics layout" |
| width=294 height=278> |
| </center> |
| |
| <p>The metrics found in <tt>face->glyph->metrics</tt> are normally |
| expressed in 26.6 pixel format (i.e 1/64th of pixels), unless you use |
| the <tt>FT_LOAD_NO_SCALE</tt> flag when calling <tt>FT_Load_Glyph()</tt> |
| or <tt>FT_Load_Char()</tt>. In that case, the metrics will be expressed |
| in original font units.</p> |
| |
| <p>The glyph slot object has a few other interesting fields that will |
| ease a developer's work. You can access them through |
| <tt>face->glyph->???</tt>:</p> |
| |
| <center> |
| <table width="90%" cellpadding=5> |
| <tr valign=top> |
| <td> |
| <tt>advance</tt> |
| </td> |
| <td> |
| This field is an <tt>FT_Vector</tt> which holds the transformed |
| advance value for the glyph. This is useful if you are using a |
| transformation through <tt>FT_Set_Transform()</tt>, as shown in the |
| rotated text example of the previous part. Other than that, its |
| value is by default (metrics.horiAdvance,0), unless you specify |
| <tt>FT_LOAD_VERTICAL</tt> when loading the glyph image; it will then |
| be (0,metrics.vertAdvance). |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>linearHoriAdvance</tt> |
| </td> |
| <td> |
| This field contains the linearly-scaled value of the glyph's |
| horizontal advance width. Indeed, the value of |
| <tt>metrics.horiAdvance</tt> that is returned in the glyph slot is |
| normally rounded to integer pixel coordinates (i.e., it will be a |
| multiple of 64) by the font driver used to load the glyph |
| image. <tt>linearHoriAdvance</tt> is a 16.16 fixed float number |
| that gives the value of the original glyph advance width in |
| 1/65536th of pixels. It can be used to perform pseudo |
| device-independent text layouts. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>linearVertAdvance</tt> |
| </td> |
| <td> |
| This is the same thing as <tt>linearHoriAdvance</tt> for the glyph's |
| vertical advance height. Its value is only reliable if the font |
| face contains vertical metrics. |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <hr> |
| |
| <h3> |
| 2. Managing glyph images |
| </h3> |
| |
| <p>The glyph image that is loaded in a glyph slot can be converted into |
| a bitmap, either by using <tt>FT_LOAD_RENDER</tt> when loading it, or by |
| calling <tt>FT_Render_Glyph()</tt> afterwards. Each time you load a new |
| glyph image, the previous one is erased from the glyph slot.</p> |
| |
| <p>There are times, however, where you may need to extract this image |
| from the glyph slot. For example, you want to cache images within your |
| application, or you want to apply additional transformations and |
| measures on it before converting it to a bitmap.</p> |
| |
| <p>The FreeType 2 API has a specific extension which is capable of |
| dealing with glyph images in a flexible and generic way. To use it, you |
| first need to include the <tt>ftglyph.h</tt> header file:</p> |
| |
| <font color="blue"> |
| <pre> |
| #include <freetype/ftglyph.h></pre> |
| </font> |
| |
| <p>We will now explain how to use the functions defined in this |
| file.</p> |
| |
| <h4> |
| a. Extracting the glyph image |
| </h4> |
| |
| <p>You can extract a single glyph image very easily. Here some code |
| that shows how to do it.</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_Glyph glyph; /* handle to glyph image */ |
| |
| |
| ... |
| error = FT_Load_Glyph( face, glyph, FT_LOAD_NORMAL ); |
| if ( error ) { .... } |
| |
| error = FT_Get_Glyph( face->glyph, &glyph ); |
| if ( error ) { .... }</pre> |
| </font> |
| |
| <p>As can be seen, we have</p> |
| |
| <ul> |
| <li> |
| created a variable, named <tt>glyph</tt>, of type |
| <tt>FT_Glyph</tt>. This is a handle (pointer) to an individual |
| glyph image, |
| </li> |
| <li> |
| loaded the glyph image normally in the face's glyph slot. We did |
| not use <tt>FT_LOAD_RENDER</tt> because we want to grab a scalable |
| glyph image in order to transform it later, |
| </li> |
| <li> |
| copied the glyph image from the slot into a new <tt>FT_Glyph</tt> |
| object by calling <tt>FT_Get_Glyph()</tt>. This function returns |
| an error code and sets <tt>glyph</tt>. |
| </li> |
| </ul> |
| |
| <p>It is important to note that the extracted glyph is in the same |
| format as the original one that is still in the slot. For example, if |
| we are loading a glyph from a TrueType font file, the glyph image will |
| really be a scalable vector outline.</p> |
| |
| <p>You can access the field <tt>glyph->format</tt> if you want to know |
| exactly how the glyph is modeled and stored. A new glyph object can |
| be destroyed with a call to <tt>FT_Done_Glyph()</tt>.</p> |
| |
| <p>The glyph object contains exactly one glyph image and a |
| 2d vector representing the glyph's advance in 16.16 fixed float |
| coordinates. The latter can be accessed directly as |
| <tt>glyph->advance</tt>.</p> |
| |
| <p><em>Note that unlike other FreeType objects, the library doesn't |
| keep a list of all allocated glyph objects. This means you will need |
| to destroy them yourself, instead of relying on |
| <tt>FT_Done_FreeType()</tt> to do all the clean-up.</em></p> |
| |
| <h4> |
| b. Transforming & copying the glyph image |
| </h4> |
| |
| <p>If the glyph image is scalable (i.e., if <tt>glyph->format</tt> is |
| not <tt>ft_glyph_format_bitmap</tt>), it is possible to transform the |
| image anytime by a call to <tt>FT_Glyph_Transform()</tt>.</p> |
| |
| <p>You can also copy a single glyph image with |
| <tt>FT_Glyph_Copy()</tt>. Here some example code:</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_Glyph glyph, glyph2; |
| FT_Matrix matrix; |
| FT_Vector delta; |
| |
| |
| ... |
| .. load glyph image in "glyph" .. |
| |
| /* copy glyph to glyph2 */ |
| error = FT_Glyph_Copy( glyph, &glyph2 ); |
| if ( error ) { ... could not copy (out of memory) } |
| |
| /* translate "glyph" */ |
| delta.x = -100 * 64; /* coordinates are in 26.6 pixels */ |
| delta.y = 50 * 64; |
| |
| FT_Glyph_Transform( glyph, 0, &delta ); |
| |
| /* transform glyph2 (horizontal shear) */ |
| matrix.xx = 0x10000L; |
| matrix.xy = 0; |
| matrix.yx = 0.12 * 0x10000L; |
| matrix.yy = 0x10000L; |
| |
| FT_Glyph_Transform( glyph2, &matrix, 0 );</pre> |
| </font> |
| |
| <p>Note that the 2x2 transformation matrix is always applied to |
| the 16.16 advance vector in the glyph; you thus don't need to |
| recompute it.</p> |
| |
| <h4> |
| c. Measuring the glyph image |
| </h4> |
| |
| <p>You can also retrieve the control (bounding) box of any glyph image |
| (scalable or not), using the <tt>FT_Glyph_Get_CBox()</tt> |
| function:</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_BBox bbox; |
| |
| |
| ... |
| FT_Glyph_Get_CBox( glyph, <em>bbox_mode</em>, &bbox );</pre> |
| </font> |
| |
| <p>Coordinates are relative to the glyph origin, i.e. (0,0), using the |
| Y upwards convention. This function takes a special argument, |
| <tt>bbox_mode</tt>, to indicate how box coordinates are expressed. If |
| <tt>bbox_mode</tt> is set to <tt>ft_glyph_bbox_subpixels</tt>, the |
| coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels). |
| |
| <p>Note that the box's maximum coordinates are exclusive, which means |
| that you can always compute the width and height of the glyph image, |
| be it in integer or 26.6 pixels with</p> |
| |
| <font color="blue"> |
| <pre> |
| width = bbox.xMax - bbox.xMin; |
| height = bbox.yMax - bbox.yMin;</pre> |
| </font> |
| |
| <p>Note also that for 26.6 coordinates, if |
| <tt>ft_glyph_bbox_gridfit</tt> is set in <tt>bbox_mode</tt>, the |
| coordinates will also be grid-fitted, which corresponds to</p> |
| |
| <font color="blue"> |
| <pre> |
| bbox.xMin = FLOOR(bbox.xMin) |
| bbox.yMin = FLOOR(bbox.yMin) |
| bbox.xMax = CEILING(bbox.xMax) |
| bbox.yMax = CEILING(bbox.yMax)</pre> |
| </font> |
| |
| <p>The default value for <tt>bbox_mode</tt> is |
| <tt>ft_glyph_bbox_pixels</tt> (i.e. integer, grid-fitted pixel |
| coordinates). Please check the API reference of |
| <tt>FT_Glyph_Get_CBox()</tt> for other possible values.</p> |
| |
| <h4> |
| d. Converting the glyph image to a bitmap |
| </h4> |
| |
| <p>You may need to convert the glyph object to a bitmap once you have |
| conveniently cached or transformed it. This can be done easily with |
| the <tt>FT_Glyph_To_Bitmap()</tt> function:</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_Vector origin; |
| |
| |
| origin.x = 32; /* 1/2 pixel in 26.6 format */ |
| origin.y = 0; |
| |
| error = FT_Glyph_To_Bitmap( &glyph, |
| <em>render_mode</em>, |
| &origin, |
| 1 ); /* destroy orig. image == true */</pre> |
| </font> |
| |
| <p>Some details on this function's parameters:</p> |
| |
| <ul> |
| <li> |
| The first parameter is <em>the address of the source glyph's |
| handle</em>. When the function is called, it reads it to access |
| the source glyph object. After the call, the handle will point to |
| a <em>new</em> glyph object that contains the rendered bitmap. |
| </li> |
| <li> |
| The second parameter is a standard render mode that is used to |
| specify what kind of bitmap we want. It can be |
| <tt>ft_render_mode_default</tt> for an 8-bit anti-aliased pixmap, |
| or <tt>ft_render_mode_mono</tt> for a 1-bit monochrome bitmap. |
| </li> |
| <li> |
| The third parameter is a pointer to a 2d vector that is used |
| to translate the source glyph image before the conversion. Note |
| that the source image will be translated back to its original |
| position (and will thus be left unchanged) after the call. If you |
| do not need to translate the source glyph before rendering, set |
| this pointer to 0. |
| </li> |
| <li> |
| The last parameter is a Boolean to indicate whether the source |
| glyph object should be destroyed by the function. By default, the |
| original glyph object is never destroyed, even if its handle is |
| lost (it's up to client applications to keep it). |
| </li> |
| </ul> |
| |
| <p>The new glyph object always contains a bitmap (when no error is |
| returned), and you must <em>typecast</em> its handle to the |
| <tt>FT_BitmapGlyph</tt> type in order to access its contents. This |
| type is a sort of <em>subclass</em> of <tt>FT_Glyph</tt> that contains |
| additional fields:</p> |
| |
| <center> |
| <table width="90%" cellpadding=5> |
| <tr valign=top> |
| <td> |
| <tt>left</tt> |
| </td> |
| <td> |
| Just like the <tt>bitmap_left</tt> field of a glyph slot, this is |
| the horizontal distance from the glyph origin (0,0) to the |
| left-most pixel of the glyph bitmap. It is expressed in integer |
| pixels. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>top</tt> |
| </td> |
| <td> |
| Just like the <tt>bitmap_top</tt> field of a glyph slot, this is |
| the vertical distance from the glyph origin (0,0) to the top-most |
| pixel of the glyph bitmap (more exactly, to the pixel just above |
| the bitmap). This distance is expressed in integer pixels, and is |
| positive for upwards Y. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>bitmap</tt> |
| </td> |
| <td> |
| This is a bitmap descriptor for the glyph object, just like the |
| <tt>bitmap</tt> field in a glyph slot. |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <hr> |
| |
| <h3> |
| 3. Global glyph metrics |
| </h3> |
| |
| <p>Unlike glyph metrics, global ones are used to describe distances and |
| features of a whole font face. They can be expressed either in 26.6 |
| pixel format or in design <em>font units</em> for scalable formats.</p> |
| |
| <h4> |
| a. Design global metrics |
| </h4> |
| |
| <p>For scalable formats, all global metrics are expressed in font |
| units in order to be later scaled to device space, according to the |
| rules described in the last chapter of this part of the tutorial. You |
| can access them directly as fields of an <tt>FT_Face</tt> handle.</p> |
| |
| <p>However, you need to check that the font face's format is scalable |
| before using them. This can be done with the macro |
| <tt>FT_IS_SCALABLE(face)</tt> which returns true if we have a scalable |
| format.</p> |
| |
| <p>In this case, you can access the global design metrics as</p> |
| |
| <center> |
| <table width="90%" cellpadding=5> |
| <tr valign=top> |
| <td> |
| <tt>units_per_EM</tt> |
| </td> |
| <td> |
| This is the size of the EM square for the font face. It is used |
| by scalable formats to scale design coordinates to device pixels, |
| as described by the last chapter of this part. Its value usually |
| is 2048 (for TrueType) or 1000 (for Type 1), but |
| other values are possible too. It is set to 1 for fixed-size |
| formats like FNT/FON/PCF/BDF. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>global_bbox</tt> |
| </td> |
| <td> |
| The global bounding box is defined as the largest rectangle that |
| can enclose all the glyphs in a font face. It is defined for |
| horizontal layouts only. This is not necessarily the smallest |
| bounding box which is possible. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>ascender</tt> |
| </td> |
| <td> |
| The ascender is the vertical distance from the horizontal baseline |
| to the height of the highest character in a font face. |
| <em>Unfortunately, font formats define the ascender |
| differently</em>. For some, it represents the ascent of all |
| capital Latin characters, without accents, for others it is the |
| ascent of the highest accented character, and finally, other |
| formats define it as being equal to <tt>global_bbox.yMax</tt>. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>descender</tt> |
| </td> |
| <td> |
| The descender is the vertical distance from the horizontal |
| baseline to the depth of the lowest character in a font face. |
| <em>Unfortunately, font formats define the descender |
| differently</em>. For some, it represents the descent of all |
| capital Latin characters, without accents, for others it is the |
| ascent of the lowest accented character, and finally, other |
| formats define it as being equal to <tt>global_bbox.yMin</tt>. |
| <em>This field is usually negative.</em> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>text_height</tt> |
| </td> |
| <td> |
| This field is used to compute a default line spacing (i.e. the |
| baseline-to-baseline distance) when writing text with this font. |
| Note that it usually is larger than the sum of the ascender and |
| descender taken as absolute values. There is also no guarantee |
| that no glyphs can extend above or below subsequent baselines when |
| using this distance. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>max_advance_width</tt> |
| </td> |
| <td> |
| This field gives the maximum horizontal cursor advance for all |
| glyphs in the font. It can be used to quickly compute the maximum |
| advance width of a string of text. <em>It doesn't correspond to |
| the maximum glyph image width!</em> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>max_advance_height</tt> |
| </td> |
| <td> |
| Same as <tt>max_advance_width</tt> but for vertical text layout. |
| It is only available in fonts providing vertical glyph metrics. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>underline_position</tt> |
| </td> |
| <td> |
| When displaying or rendering underlined text, this value |
| corresponds to the vertical position, relative to the baseline, of |
| the underline bar. It normally is negative (as it is below the |
| baseline). |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>underline_thickness</tt> |
| </td> |
| <td> |
| When displaying or rendering underlined text, this value |
| corresponds to the vertical thickness of the underline. |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <p>Notice how, unfortunately, the values of the ascender and the |
| descender are not reliable (due to various discrepancies in font |
| formats).</p> |
| |
| <h4> |
| b. Scaled global metrics |
| </h4> |
| |
| <p>Each size object also contains scaled versions of some of the |
| global metrics described above. They can be accessed directly through |
| the <tt>face->size->metrics</tt> structure.</p> |
| |
| <p>Note that these values correspond to scaled versions of the design |
| global metrics, <em>with no rounding/grid-fitting performed</em>. They |
| are also completely independent of any hinting process. In other |
| words, don't rely on them to get exact metrics at the pixel level. |
| They are expressed in 26.6 pixel format.</p> |
| |
| <center> |
| <table width="90%" cellpadding=5> |
| <tr valign=top> |
| <td> |
| <tt>ascender</tt> |
| </td> |
| <td> |
| This is the scaled version of the original design ascender. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>descender</tt> |
| </td> |
| <td> |
| This is the scaled version of the original design descender. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>height</tt> |
| </td> |
| <td> |
| The scaled version of the original design text height. This is |
| probably the only field you should really use in this structure. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>max_advance</tt> |
| </td> |
| <td> |
| This is the scaled version of the original design max advance. |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <p>Note that the <tt>face->size->metrics</tt> structure contains other |
| fields that are used to scale design coordinates to device space. |
| They are described below.</p> |
| |
| <h4> |
| c. Kerning |
| </h4> |
| |
| <p>Kerning is the process of adjusting the position of two subsequent |
| glyph images in a string of text, in order to improve the general |
| appearance of text. Basically, it means that when the glyph for an |
| "A" is followed by the glyph for a "V", the space between them can be |
| slightly reduced to avoid extra "diagonal whitespace".</p> |
| |
| <p>Note that in theory, kerning can happen both in the horizontal and |
| vertical direction between two glyphs; however, it only happens in the |
| horizontal direction in nearly all cases except really extreme |
| ones.</p> |
| |
| <p>Not all font formats contain kerning information. Instead, they |
| sometimes rely on an additional file that contains various glyph |
| metrics, including kerning, but no glyph images. A good example would |
| be the Type 1 format, where glyph images are stored in a file |
| with extension <tt>.pfa</tt> or <tt>.pfb</tt>, and where kerning |
| metrics can be found in an additional file with extension |
| <tt>.afm</tt> or <tt>.pfm</tt>.</p> |
| |
| <p>FreeType 2 allows you to deal with this by providing the |
| <tt>FT_Attach_File()</tt> and <tt>FT_Attach_Stream()</tt> APIs. Both |
| functions are used to load additional metrics into a face object, by |
| reading them from an additional format-specific file. For example, |
| you could open a Type 1 font by doing the following:</p> |
| |
| <font color="blue"> |
| <pre> |
| error = FT_New_Face( library, |
| "/usr/shared/fonts/cour.pfb", |
| 0, |
| &face ); |
| if ( error ) { ... } |
| |
| error = FT_Attach_File( face, "/usr/shared/fonts/cour.afm" ); |
| if ( error ) |
| { |
| .. could not read kerning and additional metrics .. |
| }</pre> |
| </font> |
| |
| <p>Note that <tt>FT_Attach_Stream()</tt> is similar to |
| <tt>FT_Attach_File()</tt> except that it doesn't take a C string |
| to name the extra file, but a <tt>FT_Stream</tt> handle. Also, |
| <em>reading a metrics file is in no way mandatory</em>.</p> |
| |
| <p>Finally, the file attachment APIs are very generic and can be used |
| to load any kind of extra information for a given face. The nature of |
| the additional data is entirely font format specific.</p> |
| |
| <p>FreeType 2 allows you to retrieve the kerning information |
| between two glyphs through the <tt>FT_Get_Kerning()</tt> function, |
| whose interface looks like</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_Vector kerning; |
| |
| |
| ... |
| error = FT_Get_Kerning( |
| face, /* handle to face object */ |
| left, /* left glyph index */ |
| right, /* right glyph index */ |
| <em>kerning_mode</em>, /* kerning mode */ |
| &kerning ); /* target vector */</pre> |
| </font> |
| |
| <p>As can be seen, the function takes a handle to a face object, the |
| indices of the left and right glyphs for which the kerning value is |
| desired, as well as an integer, called the <em>kerning mode</em>, and |
| a pointer to a destination vector that receives the corresponding |
| distances.</p> |
| |
| <p>The kerning mode is very similar to <tt>bbox_mode</tt> described in |
| a previous part. It is an enumeration value that indicates how the |
| kerning distances are expressed in the target vector.</p> |
| |
| <p>The default value <tt>ft_kerning_mode_default</tt> (which has |
| value 0) corresponds to kerning distances expressed in 26.6 |
| grid-fitted pixels (which means that the values are multiples |
| of 64). For scalable formats, this means that the design kerning |
| distance is scaled, then rounded.</p> |
| |
| <p>The value <tt>ft_kerning_mode_unfitted</tt> corresponds to kerning |
| distances expressed in 26.6 unfitted pixels (i.e. that do not |
| correspond to integer coordinates). It is the design kerning distance |
| that is scaled without rounding.</p> |
| |
| <p>Finally, the value <tt>ft_kerning_mode_unscaled</tt> is used to |
| return the design kerning distance, expressed in font units. You can |
| later scale it to device space using the computations explained in the |
| last chapter of this part.</p> |
| |
| <p>Note that the "left" and "right" positions correspond to the |
| <em>visual order</em> of the glyphs in the string of text. This is |
| important for bidirectional text, or when writing right-to-left |
| text.</p> |
| |
| <hr> |
| |
| <h3> |
| 4. Simple text rendering: kerning + centering |
| </h3> |
| |
| <p>In order to show off what we have just learned, we will now modify |
| the example code that was provided in the first part to render a string |
| of text, and enhance it to support kerning and delayed rendering.</p> |
| |
| <h4> |
| a. Kerning support |
| </h4> |
| |
| <p>Adding support for kerning to our code is trivial, as long as we |
| consider that we are still dealing with a left-to-right script like |
| Latin. We need to retrieve the kerning distance between two glyphs in |
| order to alter the pen position appropriately. The code looks |
| like</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_GlyphSlot slot = face->glyph; /* a small shortcut */ |
| FT_UInt glyph_index; |
| FT_Bool use_kerning; |
| FT_UInt previous; |
| int pen_x, pen_y, n; |
| |
| |
| .. initialize library .. |
| .. create face object .. |
| .. set character size .. |
| |
| pen_x = 300; |
| pen_y = 200; |
| |
| use_kerning = FT_HAS_KERNING( face ); |
| previous = 0; |
| |
| for ( n = 0; n < num_chars; n++ ) |
| { |
| /* convert character code to glyph index */ |
| glyph_index = FT_Get_Char_Index( face, text[n] ); |
| |
| /* retrieve kerning distance and move pen position */ |
| if ( use_kerning && previous && glyph_index ) |
| { |
| FT_Vector delta; |
| |
| |
| FT_Get_Kerning( face, previous, glyph_index, |
| ft_kerning_mode_default, &delta ); |
| |
| pen_x += delta.x >> 6; |
| } |
| |
| /* load glyph image into the slot (erase previous one) */ |
| error = FT_Load_Glyph( face, glyph_index, FT_LOAD_RENDER ); |
| if ( error ) continue; /* ignore errors */ |
| |
| /* now, draw to our target surface */ |
| my_draw_bitmap( &slot->bitmap, |
| pen_x + slot->bitmap_left, |
| pen_y - slot->bitmap_top ); |
| |
| /* increment pen position */ |
| pen_x += slot->advance.x >> 6; |
| |
| /* record current glyph index */ |
| previous = glyph_index; |
| }</pre> |
| </font> |
| |
| <p>We are done. Notice that</p> |
| |
| <ul> |
| <li> |
| As kerning is determined from glyph indices, we need to |
| explicitly convert our character code into a glyph index, then |
| later call <tt>FT_Load_Glyph()</tt> instead of |
| <tt>FT_Load_Char()</tt>. |
| </li> |
| <li> |
| We use a Boolean named <tt>use_kerning</tt> which is set with the |
| result of the macro <tt>FT_HAS_KERNING(face)</tt>. It is |
| certainly faster not to call <tt>FT_Get_Kerning()</tt> if we |
| know that the font face does not contain kerning information. |
| </li> |
| <li> |
| We move the position of the pen <em>before</em> a new glyph is |
| drawn. |
| </li> |
| <li> |
| We did initialize the variable <tt>previous</tt> with the |
| value 0, which always correspond to the <em>missing |
| glyph</em> (also called <tt>.notdef</tt> in the PostScript world). |
| There is never any kerning distance associated with this glyph. |
| </li> |
| <li> |
| We do not check the error code returned by |
| <tt>FT_Get_Kerning()</tt>. This is because the function always |
| set <tt>delta</tt> to (0,0) when an error occurs. |
| </li> |
| </ul> |
| |
| <h4> |
| b. Centering |
| </h4> |
| |
| <p>Our code becomes more interesting but it is still a bit too simple |
| for normal uses. For example, the position of the pen is determined |
| before we do the rendering if in a real-life situation; you would want |
| to layout the text and measure it before computing its final position |
| (e.g. centering) or perform things like word-wrapping.</p> |
| |
| <p>As a consequence we are now going to decompose our text rendering |
| function into two distinct but successive parts: The first one will |
| position individual glyph images on the baseline, while the second one |
| will render the glyphs. As will be shown, this has many |
| advantages.</p> |
| |
| <p>We start by storing individual glyph images, as well as their |
| position on the baseline. This can be done with code like</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_GlyphSlot slot = face->glyph; /* a small shortcut */ |
| FT_UInt glyph_index; |
| FT_Bool use_kerning; |
| FT_UInt previous; |
| int pen_x, pen_y, n; |
| |
| FT_Glyph glyphs[MAX_GLYPHS]; /* glyph image */ |
| FT_Vector pos [MAX_GLYPHS]; /* glyph position */ |
| FT_UInt num_glyphs; |
| |
| |
| .. initialize library .. |
| .. create face object .. |
| .. set character size .. |
| |
| pen_x = 0; /* start at (0,0)! */ |
| pen_y = 0; |
| |
| num_glyphs = 0; |
| use_kerning = FT_HAS_KERNING( face ); |
| previous = 0; |
| |
| for ( n = 0; n < num_chars; n++ ) |
| { |
| /* convert character code to glyph index */ |
| glyph_index = FT_Get_Char_Index( face, text[n] ); |
| |
| /* retrieve kerning distance and move pen position */ |
| if ( use_kerning && previous && glyph_index ) |
| { |
| FT_Vector delta; |
| |
| |
| FT_Get_Kerning( face, previous, glyph_index, |
| ft_kerning_mode_default, &delta ); |
| |
| pen_x += delta.x >> 6; |
| } |
| |
| /* store current pen position */ |
| pos[num_glyphs].x = pen_x; |
| pos[num_glyphs].y = pen_y; |
| |
| /* load glyph image into the slot. DO NOT RENDER IT! */ |
| error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT ); |
| if ( error ) continue; /* ignore errors, jump to next glyph */ |
| |
| /* extract glyph image and store it in our table */ |
| error = FT_Get_Glyph( face->glyph, &glyphs[num_glyphs] ); |
| if ( error ) continue; /* ignore errors, jump to next glyph */ |
| |
| /* increment pen position */ |
| pen_x += slot->advance.x >> 6; |
| |
| /* record current glyph index */ |
| previous = glyph_index; |
| |
| /* increment number of glyphs */ |
| num_glyphs++; |
| }</pre> |
| </font> |
| |
| <p>As you see, this is a very slight variation of our previous code |
| where we extract each glyph image from the slot, and store it, along |
| with the corresponding position, in our tables.</p> |
| |
| <p>Note also that <tt>pen_x</tt> contains the total advance for the |
| string of text. We can now compute the bounding box of the text |
| string with a simple function like</p> |
| |
| <font color="blue"> |
| <pre> |
| void compute_string_bbox( FT_BBox* abbox ) |
| { |
| FT_BBox bbox; |
| |
| |
| /* initialize string bbox to "empty" values */ |
| bbox.xMin = bbox.yMin = 32000; |
| bbox.xMax = bbox.yMax = -32000; |
| |
| /* for each glyph image, compute its bounding box, */ |
| /* translate it, and grow the string bbox */ |
| for ( n = 0; n < num_glyphs; n++ ) |
| { |
| FT_BBox glyph_bbox; |
| |
| |
| FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox ); |
| |
| glyph_bbox.xMin += pos[n].x; |
| glyph_bbox.xMax += pos[n].x; |
| glyph_bbox.yMin += pos[n].y; |
| glyph_bbox.yMax += pos[n].y; |
| |
| if ( glyph_bbox.xMin < bbox.xMin ) |
| bbox.xMin = glyph_bbox.xMin; |
| |
| if ( glyph_bbox.yMin < bbox.yMin ) |
| bbox.yMin = glyph_bbox.yMin; |
| |
| if ( glyph_bbox.xMax > bbox.xMax ) |
| bbox.xMax = glyph_bbox.xMax; |
| |
| if ( glyph_bbox.yMax &gy; bbox.yMax ) |
| bbox.yMax = glyph_bbox.yMax; |
| } |
| |
| /* check that we really grew the string bbox */ |
| if ( bbox.xMin > bbox.xMax ) |
| { |
| bbox.xMin = 0; |
| bbox.yMin = 0; |
| bbox.xMax = 0; |
| bbox.yMax = 0; |
| } |
| |
| /* return string bbox */ |
| *abbox = bbox; |
| }</pre> |
| </font> |
| |
| <p>The resulting bounding box dimensions can then be used to compute |
| the final pen position before rendering the string as in:</p> |
| |
| <font color="blue"> |
| <pre> |
| /* compute string dimensions in integer pixels */ |
| string_width = ( string_bbox.xMax - string_bbox.xMin ) / 64; |
| string_height = ( string_bbox.yMax - string_bbox.yMin ) / 64; |
| |
| /* compute start pen position in 26.6 cartesian pixels */ |
| start_x = ( ( my_target_width - string_width ) / 2 ) * 64; |
| start_y = ( ( my_target_height - string_height ) / 2 ) * 64; |
| |
| for ( n = 0; n < num_glyphs; n++ ) |
| { |
| FT_Glyph image; |
| FT_Vector pen; |
| |
| |
| image = glyphs[n]; |
| |
| pen.x = start_x + pos[n].x; |
| pen.y = start_y + pos[n].y; |
| |
| error = FT_Glyph_To_Bitmap( &image, ft_render_mode_normal, |
| &pen.x, 0 ); |
| if ( !error ) |
| { |
| FT_BitmapGlyph bit = (FT_BitmapGlyph)image; |
| |
| |
| my_draw_bitmap( bitmap->bitmap, |
| bitmap->left, |
| my_target_height - bitmap->top ); |
| |
| FT_Done_Glyph( image ); |
| } |
| }</pre> |
| </font> |
| |
| <p>Some remarks:</p> |
| |
| <ul> |
| <li> |
| The pen position is expressed in the cartesian space (i.e. |
| Y upwards). |
| </li> |
| <li> |
| We call <tt>FT_Glyph_To_Bitmap()</tt> with the <tt>destroy</tt> |
| parameter set to 0 (false), in order to avoid destroying the |
| original glyph image. The new glyph bitmap is accessed through |
| <tt>image</tt> after the call and is typecast to an |
| <tt>FT_BitmapGlyph</tt>. |
| </li> |
| <li> |
| We use translation when calling <tt>FT_Glyph_To_Bitmap()</tt>. |
| This ensures that the <tt>left</tt> and <tt>top</tt> fields of the |
| bitmap glyph object are already set to the correct pixel |
| coordinates in the cartesian space. |
| </li> |
| <li> |
| Of course, we still need to convert pixel coordinates from |
| cartesian to device space before rendering, hence the |
| <tt>my_target_height - bitmap->top</tt> in the call to |
| <tt>my_draw_bitmap()</tt>. |
| </li> |
| </ul> |
| |
| <p>The same loop can be used to render the string anywhere on our |
| display surface, without the need to reload our glyph images each |
| time.</p> |
| |
| <hr> |
| |
| <h3> |
| 5. Advanced text rendering: transformation + centering + kerning |
| </h3> |
| |
| <p>We are now going to modify our code in order to be able to easily |
| transform the rendered string, for example to rotate it. We will start |
| by performing a few minor improvements:</p> |
| |
| <h4> |
| a. packing & translating glyphs |
| </h4> |
| |
| <p>We start by packing the information related to a single glyph image |
| into a single structure instead of parallel arrays. We thus define |
| the following structure type:</p> |
| |
| <font color="blue"> |
| <pre> |
| typedef struct TGlyph_ |
| { |
| FT_UInt index; /* glyph index */ |
| FT_Vector pos; /* glyph origin on the baseline */ |
| FT_Glyph image; /* glyph image */ |
| |
| } TGlyph, *PGlyph;</pre> |
| </font> |
| |
| <p>We will also translate each glyph image directly after it is loaded |
| to its position on the baseline at load time, which has several |
| advantages. Our glyph sequence loader thus becomes:</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_GlyphSlot slot = face->glyph; /* a small shortcut */ |
| FT_UInt glyph_index; |
| FT_Bool use_kerning; |
| FT_UInt previous; |
| int pen_x, pen_y, n; |
| |
| TGlyph glyphs[MAX_GLYPHS]; /* glyphs table */ |
| PGlyph glyph; /* current glyph in table */ |
| FT_UInt num_glyphs; |
| |
| |
| .. initialize library .. |
| .. create face object .. |
| .. set character size .. |
| |
| pen_x = 0; /* start at (0,0)! */ |
| pen_y = 0; |
| |
| num_glyphs = 0; |
| use_kerning = FT_HAS_KERNING( face ); |
| previous = 0; |
| |
| glyph = glyphs; |
| for ( n = 0; n < num_chars; n++ ) |
| { |
| glyph->index = FT_Get_Char_Index( face, text[n] ); |
| |
| if ( use_kerning && previous && glyph->index ) |
| { |
| FT_Vector delta; |
| |
| |
| FT_Get_Kerning( face, previous, glyph->index, |
| ft_kerning_mode_default, &delta ); |
| |
| pen_x += delta.x >> 6; |
| } |
| |
| /* store current pen position */ |
| glyph->pos.x = pen_x; |
| glyph->pos.y = pen_y; |
| |
| error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT ); |
| if ( error ) continue; |
| |
| error = FT_Get_Glyph( face->glyph, &glyph->image ); |
| if ( error ) continue; |
| |
| /* translate the glyph image now */ |
| FT_Glyph_Transform( glyph->image, 0, &glyph->pos ); |
| |
| pen_x += slot->advance.x >> 6; |
| previous = glyph->index |
| |
| /* increment number of glyphs */ |
| glyph++; |
| } |
| |
| /* count number of glyphs loaded */ |
| num_glyphs = glyph - glyphs;</pre> |
| </font> |
| |
| <p>Translating glyphs now has several advantages, as mentioned |
| earlier. The first one is that we don't need to translate the glyph |
| bounding box when we compute the string's bounding box. The code |
| becomes:</p> |
| |
| <font color="blue"> |
| <pre> |
| void compute_string_bbox( FT_BBox* abbox ) |
| { |
| FT_BBox bbox; |
| |
| |
| bbox.xMin = bbox.yMin = 32000; |
| bbox.xMax = bbox.yMax = -32000; |
| |
| for ( n = 0; n < num_glyphs; n++ ) |
| { |
| FT_BBox glyph_bbox; |
| |
| |
| FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox ); |
| |
| if ( glyph_bbox.xMin < bbox.xMin ) |
| bbox.xMin = glyph_bbox.xMin; |
| |
| if ( glyph_bbox.yMin < bbox.yMin ) |
| bbox.yMin = glyph_bbox.yMin; |
| |
| if ( glyph_bbox.xMax > bbox.xMax ) |
| bbox.xMax = glyph_bbox.xMax; |
| |
| if ( glyph_bbox.yMax &gy; bbox.yMax ) |
| bbox.yMax = glyph_bbox.yMax; |
| } |
| |
| if ( bbox.xMin > bbox.xMax ) |
| { |
| bbox.xMin = 0; |
| bbox.yMin = 0; |
| bbox.xMax = 0; |
| bbox.yMax = 0; |
| } |
| |
| *abbox = bbox; |
| }</pre> |
| </font> |
| |
| <p><tt>compute_string_bbox()</tt> can now compute the bounding box of |
| a transformed glyph string. For example, we can do something |
| like</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_BBox bbox; |
| FT_Matrix matrix; |
| FT_Vector delta; |
| |
| |
| ... load glyph sequence |
| |
| ... setup "matrix" and "delta" |
| |
| /* transform glyphs */ |
| for ( n = 0; n < num_glyphs; n++ ) |
| FT_Glyph_Transform( glyphs[n].image, &matrix, &delta ); |
| |
| /* compute bounding box of transformed glyphs */ |
| compute_string_bbox( &bbox );</pre> |
| </font> |
| |
| <h4> |
| b. Rendering a transformed glyph sequence |
| </h4> |
| |
| <p>However, directly transforming the glyphs in our sequence is not a |
| useful idea if we want to reuse them in order to draw the text string |
| with various angles or transforms. It is better to perform the affine |
| transformation just before the glyph is rendered, as in the following |
| code:</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_Vector start; |
| FT_Matrix transform; |
| |
| |
| /* get bbox of original glyph sequence */ |
| compute_string_bbox( &string_bbox ); |
| |
| /* compute string dimensions in integer pixels */ |
| string_width = ( string_bbox.xMax - string_bbox.xMin ) / 64; |
| string_height = ( string_bbox.yMax - string_bbox.yMin ) / 64; |
| |
| /* set up start position in 26.6 cartesian space */ |
| start.x = ( ( my_target_width - string_width ) / 2 ) * 64; |
| start.y = ( ( my_target_height - string_height ) / 2 ) * 64; |
| |
| /* set up transformation (a rotation here) */ |
| matrix.xx = (FT_Fixed)( cos( angle ) * 0x10000L ); |
| matrix.xy = (FT_Fixed)(-sin( angle ) * 0x10000L ); |
| matrix.yx = (FT_Fixed)( sin( angle ) * 0x10000L ); |
| matrix.yy = (FT_Fixed)( cos( angle ) * 0x10000L ); |
| |
| for ( n = 0; n < num_glyphs; n++ ) |
| { |
| FT_Glyph image; |
| FT_Vector pen; |
| FT_BBox bbox; |
| |
| |
| /* create a copy of the original glyph */ |
| error = FT_Glyph_Copy( glyphs[n].image, &image ); |
| if ( error ) continue; |
| |
| /* transform copy (this will also translate it to the */ |
| /* correct position */ |
| FT_Glyph_Transform( image, &matrix, &start ); |
| |
| /* check bounding box -- if the transformed glyph image */ |
| /* is not in our target surface, we can avoid rendering */ |
| FT_Glyph_Get_CBox( image, ft_glyph_bbox_pixels, &bbox ); |
| if ( bbox.xMax <= 0 || bbox.xMin >= my_target_width || |
| bbox.yMax <= 0 || bbox.yMin >= my_target_height ) |
| continue; |
| |
| /* convert glyph image to bitmap (destroy the glyph */ |
| /* copy!) */ |
| error = FT_Glyph_To_Bitmap( |
| &image, |
| ft_render_mode_normal, |
| 0, /* no additional translation */ |
| 1 ); /* destroy copy in "image" */ |
| if ( !error ) |
| { |
| FT_BitmapGlyph bit = (FT_BitmapGlyph)image; |
| |
| |
| my_draw_bitmap( bitmap->bitmap, |
| bitmap->left, |
| my_target_height - bitmap->top ); |
| |
| FT_Done_Glyph( image ); |
| } |
| }</pre> |
| </font> |
| |
| <p>There are a few changes compared to the previous version of this |
| code:</p> |
| |
| <ul> |
| <li> |
| We keep the original glyph images untouched, by transforming a |
| copy. |
| </li> |
| <li> |
| We perform clipping computations in order to avoid rendering & |
| drawing glyphs that are not within our target surface. |
| </li> |
| <li> |
| We always destroy the copy when calling |
| <tt>FT_Glyph_To_Bitmap()</tt> in order to get rid of the |
| transformed scalable image. Note that the image is destroyed even |
| when the function returns an error code (which is why |
| <tt>FT_Done_Glyph()</tt> is only called within the compound |
| statement). |
| </li> |
| <li> |
| The translation of the glyph sequence to the start pen position is |
| integrated in the call to <tt>FT_Glyph_Transform()</tt> intead of |
| <tt>FT_Glyph_To_Bitmap()</tt>. |
| </li> |
| </ul> |
| |
| <p>It is possible to call this function several times to render the |
| string with different angles, or even change the way <tt>start</tt> |
| is computed in order to move it to a different place.</p> |
| |
| <p>This code is the basis of the FreeType 2 demonstration program |
| named <tt>ftstring.c</tt>. It could be easily extended to perform |
| advanced text layout or word-wrapping in the first part, without |
| changing the second one.</p> |
| |
| <p>Note however that a normal implementation would use a glyph cache |
| in order to reduce memory consumption. For example, let us assume |
| that our text string to render is "FreeType". We would store three |
| identical glyph images in our table for the letter "e", which isn't |
| optimal (especially when you consider longer lines of text, or even |
| whole pages).</p> |
| |
| <hr> |
| |
| <h3> |
| 6. Accessing metrics in design font units and scaling them |
| </h3> |
| |
| <p>Scalable font formats usually store a single vectorial image, called |
| an <em>outline</em>, for each glyph in a face. Each outline is defined |
| in an abstract grid called the <em>design space</em>, with coordinates |
| expressed in nominal <em>font units</em>. When a glyph image is loaded, |
| the font driver usually scales the outline to device space according to |
| the current character pixel size found in a <tt>FT_Size</tt> object. |
| The driver may also modify the scaled outline in order to significantly |
| improve its appearance on a pixel-based surface (a process known as |
| <em>hinting</em> or <em>grid-fitting</em>).</p> |
| |
| <p>This section describes how design coordinates are scaled to device |
| space, and how to read glyph outlines and metrics in font units. This |
| is important for a number of things:</p> |
| |
| <ul> |
| <li> |
| <p>to perform "true" WYSIWYG text layout.</p> |
| </li> |
| <li> |
| <p>to access font data for conversion or analysis purposes</p> |
| </li> |
| </ul> |
| |
| <h4> |
| a. Scaling distances to device space |
| </h4> |
| |
| <p>Design coordinates are scaled to device space using a simple |
| scaling transformation whose coefficients are computed with the help |
| of the <em>character pixel size</em>:</p> |
| |
| <font color="purple"> |
| <pre> |
| device_x = design_x * x_scale |
| device_y = design_y * y_scale |
| |
| x_scale = pixel_size_x / EM_size |
| y_scale = pixel_size_y / EM_size</pre> |
| </font> |
| |
| <p>Here, the value <tt>EM_size</tt> is font-specific and corresponds |
| to the size of an abstract square of the design space (called the |
| "EM"), which is used by font designers to create glyph images. It is |
| thus expressed in font units. It is also accessible directly for |
| scalable font formats as <tt>face->units_per_EM</tt>. You should |
| check that a font face contains scalable glyph images by using the |
| <tt>FT_IS_SCALABLE(face)</tt> macro, which returns true when the font |
| is scalable.</p> |
| |
| <p>When you call the function <tt>FT_Set_Pixel_Sizes()</tt>, you are |
| specifying the value of <tt>pixel_size_x</tt> and |
| <tt>pixel_size_y</tt>; FreeType will then immediately compute the |
| values of <tt>x_scale</tt> and <tt>y_scale</tt>.</p> |
| |
| <p>When you call the function <tt>FT_Set_Char_Size()</tt>, you are |
| specifying the character size in physical "points", which is used, |
| along with the device's resolutions, to compute the character pixel |
| size, then the scaling factors.</p> |
| |
| <p>Note that after calling any of these two functions, you can access |
| the values of the character pixel size and scaling factors as fields |
| of the <tt>face->size->metrics</tt> structure. These fields are:</p> |
| |
| <center> |
| <table width="90%" cellpadding="5"> |
| <tr valign=top> |
| <td> |
| <tt>x_ppem</t> |
| </td> |
| <td> |
| This is the size in integer pixels of the EM square, which also is |
| the <em>horizontal character pixel size</em>, called |
| <tt>pixel_size_x</tt> in the above example. <tt>x_ppem</tt> means |
| "x pixels per EM". |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>y_ppem</tt> |
| </td> |
| <td> |
| This is the size in integer pixels of the EM square, which also is |
| the <em>vertical character pixel size</em>, called |
| <tt>pixel_size_y</tt> in the above example. <tt>y_ppem</tt> means |
| "y pixels per EM". |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>x_scale</tt> |
| </td> |
| <td> |
| This is a 16.16 fixed float scale that is used to directly scale |
| horizontal distances from design space to 1/64th of device pixels. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>y_scale</tt> |
| </td> |
| <td> |
| This is a 16.16 fixed float scale that is used to directly scale |
| vertical distances from design space to 1/64th of device pixels. |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <p>You can scale a distance expressed in font units to 26.6 pixels |
| directly with the help of the <tt>FT_MulFix()</tt> function, as |
| in:</p> |
| |
| <font color="blue"> |
| <pre> |
| /* convert design distances to 1/64th of pixels */ |
| pixels_x = FT_MulFix( design_x, face->size->metrics.x_scale ); |
| pixels_y = FT_MulFix( design_y, face->size->metrics.y_scale );</pre> |
| </font> |
| |
| <p>However, you can also scale the value directly with more accuracy |
| by using doubles and the equations:</p> |
| |
| <font color="blue"> |
| <pre> |
| FT_Size_Metrics* metrics = &face->size->metrics; /* shortcut */ |
| double pixels_x, pixels_y; |
| double em_size, x_scale, y_scale; |
| |
| |
| /* compute floating point scale factors */ |
| em_size = 1.0 * face->units_per_EM; |
| x_scale = metrics->x_ppem / em_size; |
| y_scale = metrics->y_ppem / em_size; |
| |
| /* convert design distances to floating point pixels */ |
| pixels_x = design_x * x_scale; |
| pixels_y = design_y * y_scale;</pre> |
| </font> |
| |
| <h4> |
| b. Accessing design metrics (glyph & global) |
| </h4> |
| |
| <p>You can access glyph metrics in font units by specifying the |
| <tt>FT_LOAD_NO_SCALE</tt> bit flag in <tt>FT_Load_Glyph()</tt> or |
| <tt>FT_Load_Char()</tt>. The metrics returned in |
| <tt>face->glyph->metrics</tt> will then all be in font units.</p> |
| |
| <p>Unscaled kerning data can be retrieved using the |
| <tt>ft_kerning_mode_unscaled</tt> mode.</p> |
| |
| <p>Finally, a few global metrics are available directly in font units |
| as fields of the <tt>FT_Face</tt> handle, as described in |
| section 3 of this tutorial part.</p> |
| |
| <hr> |
| |
| <h3> |
| Conclusion |
| </h3> |
| |
| <p>This is the end of the second part of the FreeType 2 tutorial; |
| you are now able to access glyph metrics, manage glyph images, and |
| render text much more intelligently (kerning, measuring, transforming |
| & caching).</p> |
| |
| <p>With this knowledge you can build a pretty decent text service on top |
| of FreeType 2, and you could possibly stop there if you want.</p> |
| |
| <p>The next section will deal with FreeType 2 internals (like |
| modules, vector outlines, font drivers, renderers), as well as a few |
| font format specific issues (mainly, how to access certain TrueType or |
| Type 1 tables).</p> |
| </td></tr> |
| </table> |
| </center> |
| |
| </body> |
| </html> |