ft2faq.html

Free type 2.1.0 Documents

        <li>
          <b><tt>make lcc</tt></b> will select the Win32-lcc compiler
        </li>
      </ul>

      <p>Note that on Unix, when the first time make is called, a configure
      script located in <tt>freetype2/builds/unix</tt> will be run in order
      to automatically detect the platform & compiler.</p>

      <p>A summary will be displayed showing the detected platform and
      compiler selected.  You will then be able to start the build by
      invoking <tt>make</tt> a second time.  In case of problem, consult the
      <tt>BUILD</tt> document.</p>

      <h4>
        b. Direct compilation
      </h4>

      <p>You can also directly compile the library from the command line by
      using these simple rules:</p>

      <ul>
        <li>
          You should place the directories <tt>freetype2/include</tt> and
          <tt>freetype2/src</tt> in your include path in order to compile
          any component of the library.  You can also add the
          system-specific build directory (i.e.
          <tt>builds/<em>system</em>/</tt>) in the case where an alternate
          implementation of some of the components is available there (e.g.
          the memory-mapped i/o implementation on some Unix systems).
        </li>
        <li>
          The components of the library are located in sub-directories of
          <tt>src</tt>, for example: <tt>src/base</tt>,
          <tt>src/truetype</tt>, etc.
        </li>
        <li>
          Each component is normally compiled through a single C file that
          <em>wraps</em> other sources in the component's directory.  For
          example, you should build the TrueType font driver by compiling
          the file <tt>src/truetype/truetype.c</tt>.  The list of
          C&nbsp;files to compile for a feature-complete build of the
          library is given in the <tt>BUILD</tt> document.
        </li>
      </ul>

      <h4>
        c. Using a graphical IDE
      </h4>

      <p>Well, the process is vastly similar to the one described in b.,
      except that you need to set the include paths, source code paths, etc.
      in dialog boxes before running the compilation.</p>

    <hr>
    <a name="builds-config">
    <h3>
      II.2 How do I configure my build of the library?
    </h3>

    <p>Each build of the library is configured through two header files
    located in <tt>include/freetype/config</tt>:</p>

    <ul>
      <li>
        <tt>ftoption.h</tt>
        <br>
        This file contains various configuration macros whose definition can
        be toggled on a per-build basis.  Each macro is heavily commented in
        this file's comment, and we invite you to refer to it directly.
      </li>
      <li>
        <tt>ftmodule.h</tt>
        <br>
        This file contains the list of all the modules that are initially
        registered (added) when the function <tt>FT_Init_FreeType()</tt> is
        called.  See the next answer to know how to change it and why it may
        be important.
      </li>
    </ul>

    <p>Alternatively, some specific implementations of some FreeType&nbsp;2
    components can be provided in a <tt>builds/<em>system</em>/</tt>
    directory (e.g. the Unix-specific <tt>ftsystem.c</tt> that uses
    memory-mapped file for i/o).</p>

    <hr>
    <a name="builds-modules">
    <h3>
      II.3 How do I select the modules I need in my build?
    </h3>

    <p>The function <tt>FT_Init_FreeType()</tt> creates a new instance of
    the FreeType&nbsp;2 library and registers a set of "default" modules
    before returning to the calling application.  Its default implementation
    is in the file <tt>src/base/ftinit.c</tt>.</p>

    <p>The list of default modules used by <tt>ftinit.c</tt> is located in
    the configuration file <tt>include/freetype/config/ftmodule.h</tt>.
    Normally, it is automatically generated by the build system by invoking
    the "<tt><b>make modules</b></tt>" command in the top level
    FreeType&nbsp;2 directory (Note: this only works with GNU Make; you can
    edit the file by hand otherwise).  It does so by parsing all
    sub-directories of <tt>src</tt> that contain a file named
    <tt>module.mk</tt>.</p>

    <p>Note that a specific port or project is free to provide its own
    implementation of <tt>ftinit.c</tt> in order to ensure a different
    initialization sequence.  For example, one could do something like:</p>

    <ul>
      <li>
        Compile each module as a shared library (DLL or <tt>.so</tt>) with a
        common "entry point" to retrieve a pointer to its module class
        (there is already some code that allows this when compiling each
        module).
      </li>
      <li>
        Place these modules in a directory like
        <tt>/usr/lib/freetype2/modules/</tt>.
      </li>
      <li>
        Provide an implementation of <tt>ftinit.c</tt> that would scan the
        directory for valid modules.
      </li>
    </ul>

    <p>This example only emphasizes the flexibility that is left to
    developers when building the library.</p>

    <hr>
    <a name="builds-flat">
    <h3>
      II.4 How do I compile all FreeType&nbsp;2 files in a single
      directory?
    </h3>

    <p>Some projects may need, for the sake of simplicity or ease of
    building, to compile the FreeType&nbsp;2 library with all source files
    copied to a single directory.  This is possible.</p>

    <p>To do so, you have to copy all source files located under
    <tt>src</tt> to your own directory (you must retain the include files in
    a distinct hierarchy though), then compile each of the FreeType&nbsp;2
    component with the macro <tt>FT_FLAT_COMPILE</tt>.  This will change the
    way <tt>#include</tt> works during the build.</p>

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

  <br>

  <table width="100%">
    <tr bgcolor="#CCCCEE"><td>
    <h2 align=center>
      <a name="autohint">The FreeType&nbsp;2 auto-hinter
    </h2>
  </td></tr>
  <tr><td>

    <a name="autohint-license">
    <h3>
      III.1 Under which license is the FreeType&nbsp;2 auto-hinter released?
    </h3>

    <p>The auto-hinter was initially designed and implemented under contract
    for <a href="http://www.catharon.com">Catharon Productions, Inc</a>
    which gladly accepted to released it under an open-source license
    compatible with the FreeType one.</p>

    <p>This license can be found in
    <tt>src/autohint/CatharonLicense.txt</tt> and requires that you cite
    Catharon Productions in your documentation (just like you do with
    FreeType) when using the auto-hinting module.</p>

    <p>Other than that, you still have the same freedom than with the good
    old FreeType license.  Enjoy!</p>

    <hr>
    <a name="autohint-work">
    <h3>
      III.2 How does the auto-hinter work?
    </h3>

    <p>Well, a complete description would be difficult.  Have a look at the
    dedicated <a href="autohinting/index.html">auto-hinter pages</a> on the
    FreeType site, as they describe most of its details with graphics and
    explanations.  You could also look at the source code if you want
    to&nbsp;:-)</p>

    <p>To give a few details, the auto-hinter is used to perform
    grid-fitting on scalable font formats that use B&eacute;zier outlines as
    their primary glyph image format (this means nearly all scalable font
    formats today).  If a given font driver doesn't provide its own hinter,
    the auto-hinter is used by default.  If a format-specific hinter is
    provided, it is still possible to use the auto-hinter using the
    <tt>FT_LOAD_FORCE_AUTOHINT</tt> bit flag when calling
    <tt>FT_Load_Glyph()</tt>.</p>

    <p>The auto-hinter currently doesn't use external hints to do its job,
    as it automatically computes global metrics (when it "opens" a font for
    the first time) and glyph "hints" from their outline.  Note that we plan
    the ability to specify external hints, given that it is based on a
    constraint system.  That could be used to support native hints in
    Type&nbsp;1/Type&nbsp;2 fonts, for example.</p>

    <hr>
    <a name="autohint-cjk">
    <h3>
      III.3 Why does the auto-hinter doesn't work correctly with CJK
      fonts?
    </h3>

    <p>The auto-hinter was first designed to manage and hint Latin-based
    fonts, as they consist of most of the fonts available today.  It doesn't
    hint Asian fonts, as well as a few other complex scripts, because we
    didn't put enough research on the topic yet.  Hinting CJK isn't really
    more difficult than Latin, just different, with a set of different
    constraints (basically, more distortion of glyphs is acceptable as long
    as certain features like triple-stem positions are respected more
    strictly).</p>

    <p>We thus plan to handle such a case in the near future.  Please be
    patient.</p>
  </td></tr>
  </table>

  <br>

  <table width="100%">
  <tr bgcolor="#CCCCEE"><td>
    <h2 align=center>
      <a name="other">Other questions
    </h2>
  </td></tr>
  <tr><td>

    <a name="other-depth">
    <h3>
      IV.1 Can I use FreeType to draw text on a pixmap with arbitratry depth?
    </h3>

    <p>Not directly, as FreeType is a font library, not a general purpose
    graphics library or text rendering service.  However, note that the
    anti-aliased renderer allows you to convert a vectorial glyph outline
    into a list of "spans" (i.e. horizontal pixel segments with same
    coverage) that can be rendered through user-provided callbacks.</p>

    <p>By providing the appropriate span callback, you can render
    anti-aliased text to any kind of surface.  You can also use any color or
    fill pattern/image if you want to.  This process is called <em>direct
    rendering</em>.  For more information, please read the documentation
    contained in the following files:</p>
     
    <ul>
      <li>
        <p><tt>&lt;freetype/ftimage.h&gt;</tt> contains the definition of
        the <tt>FT_Raster_Params</tt> type used with direct rendering.</p>
      </li>
      <li>
        <p><tt>&lt;freetype/ftoutln.h&gt;</tt> contains the definition of
        the <tt>FT_Outline_Render()</tt> function that can be used to
        convert vectorial outlines to span lists.</p>
      </li>
    </ul>

    <p>Here's some code that uses them:</p>

    <font color="blue"><pre>
    FT_Raster_Params  params;
    FT_Outline        outline;
       

    ... load vectorial glyph in "outline" ...
       
    params.flags      = ft_raster_flag_aa | ft_raster_flag_direct;
    params.gray_spans = (FT_Raster_Span_Func)your_own_span_function_here;
    params.user       = your_own_data_pointer;
       
    error = FT_Outline_Render( library, &amp;outline, &amp;params );</pre>
    </font>
     
    <p>Note that direct rendering is <em>not</em> available with monochrome
    output, as the current renderer uses a two-pass algorithm to generate
    glyphs with correct drop-out control.</p>

    <hr>
    <a name="other-color">
    <h3>
      IV.2 How can I set the color of text rendered by FreeType?
    </h3>

    <p>Basically, you can't do that, because FreeType is simply a font
    library.  In general, you will need to use your favorite graphics
    library to draw the FreeType glyphs with the appropriate color.</p>

    <p>Note that for anti-aliased glyphs, you can "set the color" by using
    <em>direct rendering</em> as described in <a href="#other-depth">this
    answer</a>.</p>

    <hr>
    <a name="other-size">
    <h3>
      IV.3 I set the pixel size to 8x8, but the resulting glyphs are larger
      (or smaller) than that.  Why?
    </h3>

    <p>A lot of people have difficulties to understand this topic, because
    they think of glyphs as fixed-width resp. fixed-height "cells", like
    those of fonts used in terminals/consoles.  This assumption is simply
    not valid with most "modern" font formats, even bitmapped-based ones
    like <tt>PCF</tt> or <tt>BDF</tt>.</p>

    <p>Be aware that the <em>character size</em> that is set either through
    <tt>FT_Set_Char_Size()</tt> or <tt>FT_Set_Pixel_Sizes()</tt> isn't
    directly related to the dimension of the glyph bitmaps generated.</p>
    
    <p>Rather, the character size is indeed the size of <em>an abstract
    square</em>, called the <em>EM</em>, used by typographers to design
    fonts.  Scaling two distinct fonts to the same character size, be it
    expressed in points or pixels, will generally result in bitmaps with
    <em>distinct dimensions</em>!</p>

    <p>Note that historically, the EM corresponded to the width of a capital
    "M" in Latin typefaces.  However, later improvements in typography led
    to designs that greatly detract from this rule.  Today, it is not
    possible to connect the EM size to a specific font "feature" in a
    reliable way.</p>

    <hr>
    <a name="other-bbox">
    <h3>
      IV.4 How can I compute the bounding box of a given string of text
      without loading its glyphs before?
    </h3>
    
    <p>A lot of people want to be able to compute the size in pixels of a
    simple string of text with minimal overhead.  For example, that can be
    useful to draw centered text within a button. (to be continued...)</p>

    <hr>
    <a name="other-antialias">
    <h3>
      IV.5 Which anti-aliasing algorithm is used by FreeType&nbsp;2?</h3>

    <p>The algorithm has been specifically designed for FreeType.  It is
    based on ideas that were originally found in the implementation of the
    <a href="http://www.levien.com/libart">libArt</a> graphics library to
    compute the <em>exact pixel coverage</em> of a vector image with
    absolutely no sub-sampling/filtering.</p>

    <p>However, these two implementations are radically distinct and use
    vastly different models.  The FreeType&nbsp;2 renderer is optimized
    specifically for rendering small complex shapes, like glyphs, at very
    high speed while using very few memory; while libArt shines at general
    shape/polygon processing, especially large ones.</p>

    <p>The FreeType&nbsp;2 anti-aliasing renderer is indeed <em>faster</em>
    than the monochrome renderer for small character sizes (typically
    &lt;20&nbsp;pixels).  The reason is that the monochrome renderer must
    perform two passes on the outline in order to perform drop-out control
    according to the TrueType specification (we could drop this requirement
    later though).</p>

    <p>We will try to document its design in a later document, though this
    is not a priority for now.</p>

    <hr>
    <a name="other-opentype">
    <h3>
      IV.6 When will FreeType&nbsp;2 support OpenType?
    </h3>

    <p>Well, the engine already reads OpenType/CFF files perfectly.  What it
    doesn't do is handle "OpenType Layout" tables yet.</p>

    <p>FreeType&nbsp;1 comes with a set of extensions that are used to load
    and manage OpenType Layout tables.  It even has a demonstration program
    named <tt>ftstrtto</tt> to show its capabilities.</p>

    <p>For FreeType&nbsp;2, we have decided that the layout operations
    provided through these tables are better placed in a specific
    text-layout library, (many people having asked for such a thing).  This
    new engine will not depend on FreeType2 explicitly and will be developed
    as a separate project.  We plan to announce it in a few weeks with all
    gory details, once the definitive 2.0&nbsp;release of FreeType has been
    made.</p>

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

  <p><hr></p>

  <a href="index.html">Back to FreeType homepage</a><p>

</td></tr>
</table>
</body>
</html>