step2.html

documentation for freetype 2.2.1

  ...
  FT_Glyph_Get_CBox( glyph, <em>bbox_mode</em>, &amp;bbox );
      </div>

      <p>Coordinates are relative to the glyph origin (0,0), using the
      y&nbsp;upwards convention.  This function takes a special argument,
      the <em>bbox mode</em>, to indicate how box coordinates are
      expressed.</p>

      <p>If the glyph has been loaded with <tt>FT_LOAD_NO_SCALE</tt>,
      <tt>bbox_mode</tt> must be set to <tt>FT_GLYPH_BBOX_UNSCALED</tt> to
      get unscaled font units in 26.6 pixel format.  The value
      <tt>FT_GLYPH_BBOX_SUBPIXELS</tt> is another name for this
      constant.</p>

      <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 in in integer or 26.6 pixels, with:</p>

      <div class="pre">
  width  = bbox.xMax - bbox.xMin;
  height = bbox.yMax - bbox.yMin;
      </div>

      <p>Note also that for 26.6 coordinates, if
      <tt>FT_GLYPH_BBOX_GRIDFIT</tt> is used as the bbox mode, the
      coordinates will also be grid-fitted, which corresponds to</p>

      <div class="pre">
  bbox.xMin = FLOOR( bbox.xMin )
  bbox.yMin = FLOOR( bbox.yMin )
  bbox.xMax = CEILING( bbox.xMax )
  bbox.yMax = CEILING( bbox.yMax )
      </div>

      <p>To get the bbox in <em>integer</em> pixel coordinates, set
      <tt>bbox_mode</tt> to <tt>FT_GLYPH_BBOX_TRUNCATE</tt>.</p>

      <p>Finally, to get the bounding box in grid-fitted pixel coordinates,
      set <tt>bbox_mode</tt> to <tt>FT_GLYPH_BBOX_PIXELS</tt>.

      <h4>
        d.&nbsp;Converting the glyph image to a bitmap
      </h4>

      <p>You may need to convert the glyph object to a bitmap once you have
      convienently cached or transformed it.  This can be done easily with
      the <a href="../reference/ft2-glyph_management.html">
      <tt>FT_Glyph_To_Bitmap</tt></a> function. It is in charge of
      converting any glyph object into a bitmap, as in:</p>

      <div class="pre">
  FT_Vector  origin;


  origin.x = 32; <span class="comment">/* 1/2 pixel in 26.6 format */</span>    
  origin.y = 0;

  error = FT_Glyph_To_Bitmap(
            &amp;glyph,
            <em>render_mode</em>,
            &amp;origin,
            1 );          <span class="comment">/* destroy original image == true */</span>    
      </div>

      <p>Some notes:</p>

      <ul>
        <li>
          <p>The first parameter is the address of the source glyph's
          handle.  When the function is called, it reads its 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.</p>
        </li>

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

        <li>
          <p>The third parameter is a pointer to a two-dimensional 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&nbsp;0.</p>
        </li>

        <li>
          <p>The last parameter is a boolean that indicates whether the
          source glyph object should be destroyed by the function.  If
          false, the original glyph object is never destroyed, even if its
          handle is lost (it is up to client applications to keep it).</p>
        </li>
      </ul>

      <p>The new glyph object always contains a bitmap (if no error is
      returned), and you must <em>typecast</em> its handle to the
      <tt>FT_BitmapGlyph</tt> type in order to access its content.  This
      type is a sort of &lsquo;subclass&rsquo; of <tt>FT_Glyph</tt> that
      contains additional fields (see <a
      href="../reference/ft2-glyph_management.html#FT_BitmapGlyphRec">
      <tt>FT_BitmapGlyphRec</tt></a>):</p>

      <center>
      <table width="80%" cellpadding=5>
      <tr valign=top>
        <td>
          <tt>left</tt>
        </td>
        <td>
          <p>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
          leftmost pixel of the glyph bitmap.  It is expressed in integer
          pixels.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>top</tt>
        </td>
        <td>
          <p>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
          topmost pixel of the glyph bitmap (more precise, to the pixel just
          above the bitmap).  This distance is expressed in integer pixels,
          and is positive for upwards&nbsp;y.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>bitmap</tt>
        </td>
        <td>
          <p>This is a bitmap descriptor for the glyph object, just like the
          <tt>bitmap</tt> field in a glyph slot.</p>
        </td>
      </tr>
      </table>
      </center>

    <hr>

    <h3>
      3.&nbsp;Global glyph metrics
    </h3>

    <p>Unlike glyph metrics, global metrics 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 &lsquo;font units&rsquo; for scalable
    formats.</p>

      <h4>
        a.&nbsp;Design global metrics
      </h4>

      <p>For scalable formats, all global metrics are expressed in font
      units in order to be later scaled to the device space, according to
      the rules described in the last chapter of this section of the
      tutorial.  You can access them directly as simple fields of a
      <tt>FT_Face</tt> handle.</p>

      <p>However, you need to check that the font face's format is scalable
      before using them.  One can do it by using the macro
      <tt>FT_IS_SCALABLE</tt> which returns true when appropriate.</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>
          <p>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 in the last chapter of this section.  Its
          value usually is 2048 (for TrueType) or 1000 (for Type&nbsp;1),
          but others are possible too.  It is set to&nbsp;1 for fixed-size
          formats like FNT/FON/PCF/BDF.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>global_bbox</tt>
        </td>
        <td>
          <p>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.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>ascender</tt>
        </td>
        <td>
          <p>The ascender is the vertical distance from the horizontal
          baseline to the highest &lsquo;character&rsquo; coordinate in a
          font face.  Unfortunately, font formats define the ascender
          differently.  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>.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>descender</tt>
        </td>
        <td>
          <p>The descender is the vertical distance from the horizontal
          baseline to the lowest &lsquo;character&rsquo; coordinate in a
          font face.  Unfortunately, font formats define the descender
          differently.  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>.  This field is
          negative for values below the baseline.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>text_height</tt>
        </td>
        <td>
          <p>This field is simply 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 extend above or below subsequent
          baselines when using this distance.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>max_advance_width</tt>
        </td>
        <td>
          <p>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></p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>max_advance_height</tt>
        </td>
        <td>
          <p>Same as <tt>max_advance_width</tt> but for vertical text
          layout.  It is only available in fonts providing vertical glyph
          metrics.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>underline_position</tt>
        </td>
        <td>
          <p>When displaying or rendering underlined text, this value
          corresponds to the vertical position, relative to the baseline, of
          the underline bar.  It is negative if it is below the
          baseline.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>underline_thickness</tt>
        </td>
        <td>
          <p>When displaying or rendering underlined text, this value
          corresponds to the vertical thickness of the underline.</p>
        </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.&nbsp;Scaled global metrics
      </h4>

      <p>Each size object also contains a scaled versions of some of the
      global metrics described above.  They can be accessed directly through
      the <tt>face-&gt;size-&gt;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="80%" cellpadding=5>
      <tr valign=top>
        <td>
         <tt>ascender</tt>
        </td>
        <td>
          <p>The scaled version of the original design ascender.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>descender</tt>
        </td>
        <td>
          <p>The scaled version of the original design descender.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>height</tt>
        </td>
        <td>
          <p>The scaled version of the original design text height.  This
          is probably the only field you should really use in this
          structure.</p>
        </td>
      </tr>
      <tr valign=top>
        <td>
          <tt>max_advance</tt>
        </td>
        <td>
          <p>The scaled version of the original design max advance.</p>
        </td>
      </tr>
      </table>
      </center>

      <p>Note that the <tt>face-&gt;size-&gt;metrics</tt> structure contains
      other fields that are used to scale design coordinates to device
      space.  They are described in the last chapter.</p>

      <h4>
        c.&nbsp;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
      &lsquo;A&rsquo; is followed by the glyph for a &lsquo;V&rsquo;, the
      space between them can be slightly reduced to avoid extra
      &lsquo;diagonal whitespace&rsquo;.</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 is
      the Type&nbsp;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&nbsp;2 allows you to deal with this, by providing the <a
      href="../reference/ft2-base_interface.html#FT_Attach_File">
      <tt>FT_Attach_File</tt></a> and <a
      href="../reference/ft2-base_interface.html#FT_Attach_Stream">
      <tt>FT_Attach_Stream</tt></A> 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&nbsp;1 font by doing the following:</p>

      <div class="pre">
  error = FT_New_Face( library, "/usr/shared/fonts/cour.pfb",
                       0, &amp;face );
  if ( error ) { ... }

  error = FT_Attach_File( face, "/usr/shared/fonts/cour.afm" );
  if ( error )
  { ... could not read kerning and additional metrics ... }
      </div>

      <p>Note that <tt>FT_Attach_Stream</tt> is similar to
      <tt>FT_Attach_File</tt> except that it doesn't take a C&nbsp;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 content is entirely font format specific.</p>

      <p>FreeType&nbsp;2 allows you to retrieve the kerning information for
      two glyphs through the <tt>FT_Get_Kerning</tt> function, whose
      interface looks like:</p>

      <div class="pre">
  FT_Vector  kerning;


  ...
  error = FT_Get_Kerning( face,          <span class="comment">/* handle to face object */</span>    
                          left,          <span class="comment">/* left glyph index      */</span>    
                          right,         <span class="comment">/* right glyph index     */</span>    
                          <em>kerning_mode</em>,  <span class="comment">/* kerning mode          */</span>    
                          &amp;kerning );    <span class="comment">/* target vector         */</span>    
      </div>

      <p>As you see, the function takes a handle to a face object, the
      indices of the left and right glyph 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>