step2.html

documentation for freetype 2.2.1

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

    <span class="comment">/* store current pen position */</span>    
    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-&gt;glyph, &amp;glyph-&gt;image );
    if ( error ) continue;

    <span class="comment">/* translate the glyph image now */</span>    
    FT_Glyph_Transform( glyph-&gt;image, 0, &amp;glyph-&gt;pos );

    pen_x   += slot->advance.x &gt;&gt; 6;
    previous = glyph->index;

    <span class="comment">/* increment number of glyphs */</span>    
    glyph++;
  }

  <span class="comment">/* count number of glyphs loaded */</span>    
  num_glyphs = glyph - glyphs;
      </div>

      <p>Note that translating glyphs now has several advantages.  The first
      one is that we don't need to translate the glyph bbox when we compute
      the string's bounding box.  The code becomes:</p>

      <div class="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 &lt; num_glyphs; n++ )
    {
      FT_BBox  glyph_bbox;


      FT_Glyph_Get_CBox( glyphs[n], &amp;glyph_bbox );

      if (glyph_bbox.xMin &lt; bbox.xMin)
        bbox.xMin = glyph_bbox.xMin;

      if (glyph_bbox.yMin &lt; bbox.yMin)
        bbox.yMin = glyph_bbox.yMin;

      if (glyph_bbox.xMax &gt; bbox.xMax)
        bbox.xMax = glyph_bbox.xMax;

      if (glyph_bbox.yMax &gt; 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;
  }
      </div>

      <p>Now take a closer look: The <tt>compute_string_bbox</tt> function
      can now compute the bounding box of a transformed glyph string.  For
      example, we can do something like:</p>

      <div class="pre">
  FT_BBox    bbox;
  FT_Matrix  matrix;
  FT_Vector  delta;


  ... load glyph sequence ...
  ... setup "matrix" and "delta" ...

  <span class="comment">/* transform glyphs */</span>    
  for ( n = 0; n &lt; num_glyphs; n++ )
    FT_Glyph_Transform( glyphs[n].image, &amp;matrix, &amp;delta );

  <span class="comment">/* compute bounding box of transformed glyphs */</span>    
  compute_string_bbox( &amp;bbox );
      </div>

      <h4>
        b.&nbsp;Rendering a transformed glyph sequence
      </h4>

      <p>However, directly transforming the glyphs in our sequence is not a
      good idea if we want to reuse them in order to draw the text string
      with various angles or transformations.  It is better to perform the
      affine transformation just before the glyph is rendered, as in the
      following code:</p>

      <div class="pre">
  FT_Vector  start;
  FT_Matrix  transform;


  <span class="comment">/* get bbox of original glyph sequence */</span>    
  compute_string_bbox( &amp;string_bbox );

  <span class="comment">/* compute string dimensions in integer pixels */</span>    
  string_width  = (string_bbox.xMax - string_bbox.xMin) / 64;
  string_height = (string_bbox.yMax - string_bbox.yMin) / 64;

  <span class="comment">/* set up start position in 26.6 cartesian space */</span>    
  start.x = ( ( my_target_width  - string_width  ) / 2 ) * 64;
  start.y = ( ( my_target_height - string_height ) / 2 ) * 64;

  <span class="comment">/* set up transform (a rotation here) */</span>
  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 &lt; num_glyphs; n++ )
  {
    FT_Glyph  image;
    FT_Vector pen;
    FT_BBox   bbox;

    <span class="comment">/* create a copy of the original glyph */</span>
    error = FT_Glyph_Copy( glyphs[n].image, &amp;image );
    if ( error ) continue;

    <span class="comment">/* transform copy (this will also translate it to the */</span>
    <span class="comment">/* correct position                                   */</span>
    FT_Glyph_Transform( image, &amp;matrix, &amp;start );

    <span class="comment">/* check bounding box; if the transformed glyph image      */</span>
    <span class="comment">/* is not in our target surface, we can avoid rendering it */</span>
    FT_Glyph_Get_CBox( image, ft_glyph_bbox_pixels, &amp;bbox );
    if ( bbox.xMax &lt;= 0 || bbox.xMin &gt;= my_target_width  ||
         bbox.yMax &lt;= 0 || bbox.yMin &gt;= my_target_height )
      continue;

    <span class="comment">/* convert glyph image to bitmap (destroy the glyph copy!) */</span>
    error = FT_Glyph_To_Bitmap(
              &amp;image,
              FT_RENDER_MODE_NORMAL,
              0,                  <span class="comment">/* no additional translation */</span>
              1 );                <span class="comment">/* destroy copy in "image"   */</span>
    if ( !error )
    {
      FT_BitmapGlyph  bit = (FT_BitmapGlyph)image;


      my_draw_bitmap( bitmap-&gt;bitmap,
                      bitmap-&gt;left,
                      my_target_height - bitmap-&gt;top );

      FT_Done_Glyph( image );
    }
  }
      </div>

      <p>There are a few changes compared to the original version of this
      code:</p>

      <ul>
        <li>
          <p>We keep the original glyph images untouched; instead, we
          transform a copy.</p>
        </li>

        <li>
          <p>We perform clipping computations in order to avoid rendering
          &amp; drawing glyphs that are not within our target surface</p>
        </li>

        <li>
          <p>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.</p>
        </li>

        <li>
          <p>The translation of the glyph sequence to the start pen position
          is integrated in the call to <tt>FT_Glyph_Transform</tt> instead
          of <tt>FT_Glyph_To_Bitmap</tt>.</p>
        </li>
      </ul>

      <p>It is possible to call this function several times to render the
      string width different angles, or even change the way <tt>start</tt>
      is computed in order to move it to different place.</p>

      <p>This code is the basis of the FreeType&nbsp;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 needs.  For example, let us assume that our
      text string is &lsquo;FreeType&rsquo'.  We would store three identical
      glyph images in our table for the letter &lsquo;e&rsquo;, which isn't
      optimal (especially when you consider longer lines of text, or even
      whole pages).</p>

    <hr>

    <h3>
      6.&nbsp;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 chapter describes how design coordinates are scaled to the
    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>&lsquo;true&rsquo; WYSIWYG text layout</p>
      </li>
      <li>
        <p>accessing font content for conversion or analysis purposes</p>
      </li>
    </ul>

      <h4>
        a.&nbsp;Scaling distances to device space
      </h4>

      <p>Design coordinates are scaled to the device space using a simple
      scaling transformation whose coefficients are computed with the help
      of the <em>character pixel size</em>:</p>

      <div class="example">
  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
      </div>

      <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>EM</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-&gt;units_per_EM</tt>.  You
      should check that a font face contains scalable glyph images by using
      the <tt>FT_IS_SCALABLE</tt> macro, which returns true when
      appropriate.</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 shall use.  The library will
      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 <em>points</em>, which is
      used, along with the device's resolutions, to compute the character
      pixel size and the corresponding 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-&gt;size-&gt;metrics</tt> structure.  These fields
      are:</p>

      <center>
      <table width="80%" cellpadding="5">
      <tr valign=top>
        <td>
          <tt>x_ppem</tt>
        </td>
        <td>
          <p>The field name stands for &lsquo;x&nbsp;pixels per EM&rsquo;;
          this is the horizontal 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.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>y_ppem</tt>
        </td>
        <td>
          <p>The field name stands for &lsquo;y&nbsp;pixels per EM&rsquo;;
          this is the vertical 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.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>x_scale</tt>
        </td>
        <td>
          <p>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.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>y_scale</tt>
        </td>
        <td>
          <p>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.</p>
        </td>
      </tr>
      </table>
      </center>

      <p>You can scale a distance expressed in font units to 26.6 pixel
      format directly with the help of the <tt>FT_MulFix</tt> function, as
      in:</p>

      <div class="pre">
  <span class="comment">/* convert design distances to 1/64th of pixels */</span>
  pixels_x = FT_MulFix( design_x, face-&gt;size-&gt;metrics.x_scale );
  pixels_y = FT_MulFix( design_y, face-&gt;size-&gt;metrics.y_scale );
      </div>

      <p>However, you can also scale the value directly with more accuracy
      by using doubles:</p>

      <div class="pre">
  FT_Size_Metrics*  metrics = &amp;face-&gt;size-&gt;metrics; <span class="comment">/* shortcut */</span>
  double            pixels_x, pixels_y;
  double            em_size, x_scale, y_scale;


  <span class="comment">/* compute floating point scale factors */</span>
  em_size = 1.0 * face-&gt;units_per_EM;
  x_scale = metrics-&gt;x_ppem / em_size;
  y_scale = metrics-&gt;y_ppem / em_size;

  <span class="comment">/* convert design distances to floating point pixels */</span>
  pixels_x = design_x * x_scale;
  pixels_y = design_y * y_scale;
      </div>

      <h4>
        b.&nbsp;Accessing design metrics (glyph &amp; global)
      </h4>

      <p>You can access glyph metrics in font units simply 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-&gt;glyph-&gt;metrics</tt> will all be in font units.</p>

      <p>You can access unscaled kerning data 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
      chapter&nbsp;3 of this section.</p>

    <hr>

    <h3>
      Conclusion
    </h3>

    <p>This is the end of the second section of the FreeType&nbsp;2
    tutorial.  You are now able to access glyph metrics, manage glyph
    images, and render text much more intelligently (kerning, measuring,
    transforming &amp; caching).</p>

    <p>You have now sufficient knowledge to build a pretty decent text
    service on top of FreeType&nbsp;2, and you could possibly stop here if
    you want.</p>

    <p>The next section will deal with FreeType&nbsp;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&nbsp;1 tables).  [This section has not been written yet.]</p>

</td></tr>
</table>
</center>

<h3 align=center>
  <a href="step1.html">FreeType&nbsp;2 Tutorial Step&nbsp;1</a>
</h3>

</body>
</html>