This file is an attempt  at explaining the internals of the FreeType
rasterizer.   This  component is  quite  general  purpose and  could
easily  be  integrated into  other  programs  (but  still under  the
current license).

--------------------------------------------------------------------

            The HOWs and WHYs of the FreeType rasterizer

                          by David Turner


  I. Introduction

 II. Rendering Technology

III. Implementation Details

 IV. Gray-Level Support



I. Introduction
===============

  A  rasterizer is  a library  in charge  of converting  a vectorial
  representation of a shape  into a bitmap.  The FreeType rasterizer
  has been developed  to render the glyphs found  in TrueType files,
  made up of segments and second-order Beziers.  This document is an
  explanation of its design and implementation.

  Though these  explanations start from  the basics, a  knowledge of
  common rasterization techniques is assumed.


--------------------------------------------------------------------


II. Rendering Technology
========================

1. Requirements
---------------

  We will assume that all scaling/rotating/hinting/whatever has been
  already done.   The glyph  is thus described,  as in  the TrueType
  specification, by  a list of  points.  Each point  has an x  and y
  coordinate, as well as a  flag that indicates whether the point is
  _on_ or _off_ the curve.
  
  More precisely:

  - All  point coordinates  are in  the 26.6  fixed float  format as
    defined by the specification.  The orientation used is:

       ^ y
       |         reference orientation
       |
       *----> x
     0

    This means  that the `distance' between  two neighbouring pixels
    is 64 `units' (1 unit = 1/64th of a pixel).

    Note  that, for  the rasterizer,  pixel centers  are  located at
    integer coordinates,  i.e., (0.0, 0.0) is the  coordinate of the
    origin's  center  (unlike   what  happens  within  the  TrueType
    bytecode  interpreter where  this point's  center lies  at (0.5,
    0.5)).

    A pixel line in the target bitmap is called a `scanline'.

  - A  glyph  is  usually  made  of several  contours,  also  called
    outlines.  A contour  is simply a closed curve  that delimits an
    outer or inner region of the glyph.  It is described by a series
    of successive points of the points table.

    Each point  of the glyph  has an associated flag  that indicates
    whether  it is  `on' or  `off' the  curve.  Two  successive `on'
    points indicate a line segment joining the two points.

    One `off' point amidst two `on' points indicates a second degree
    Bezier parametric arc, defined  by these three points (the `off'
    point being the  control point, and the `on'  ones the start and
    end points).
     
    Finally, two  successive `off'  points forces the  rasterizer to
    create, during  rendering, an `on'  point amidst them,  at their
    exact  middle.   This  greatly  facilitates  the  definition  of
    successive Bezier arcs.

                                        *            # on curve
                                                     * off curve
                                     __---__
        #-__                      _--       -_
            --__                _-            -
                --__           #               \ 
                    --__                        #
                        -#
                                 Two `on' points
         Two `on' points       and one `off' point
                                  between them

                      *
        #            __      Two `on' points with two `off'
         \          -  -     points between them. The point
          \        /    \    marked `0' is the middle of the
           -      0      \   `off' points, and is a `virtual
            -_  _-       #   on' point where the curve passes.
              --             It does not appear in the point
              *              list.


  The FreeType  rasterizer, as  intended to render  TrueType glyphs,
  does  not support  third order  Beziers, usually  found in  Type 1
  fonts.   Type 1  support may  lead to  further development  of the
  engine (it is already part of FreeType 2.0).

  The parametric form of a second-order Bezier is:

      P(t) = (1-t)^2*P1 + 2*t*(1-t)*P2 + t^2*P3

         with t a real number in the range [0..1]

  P1 and P3 are the endpoints, P2 the control point.

  Note that the rasterizer does  not use this formula.  It exhibits,
  however, one  very useful property  of Bezier arcs: Each  point of
  the curve is a weighted average of the control points.

  As all weights  are positive and always sum up  to 1, whatever the
  value of t, each arc point lies within the triangle defined by the
  arc's three control points.


2. Profiles and Spans
---------------------

  The following is a basic explanation of the _kind_ of computations
  made  by  the   rasterizer  to  build  a  bitmap   from  a  vector
  representation.  Note  that the actual  implementation is slightly
  different, due to performance tuning and other factors.

  However, the following ideas remain  in the same category, and are
  more convenient to understand.

  a. Sweeping the shape

    The best way to fill a shape is to decompose it into a number of
    simple  horizontal segments,  then turn  them on  in  the target
    bitmap.  These segments are called `spans'.

                __---__
             _--       -_
           _-            -
          -               \
         /                 \
        /                   \
       |                     \

                __---__         Example: filling a shape
             _----------_                with spans.
           _--------------
          ----------------\ 
         /-----------------\    This is typically done from the top
        /                   \   to the bottom of the shape, in a
       |           |         \  movement called a `sweep".
                   V

                __---__
             _----------_
           _--------------
          ----------------\ 
         /-----------------\
        /-------------------\
       |---------------------\
                    
     
    In  order  to draw  a  span,  the  rasterizer must  compute  its
    coordinates,   which   are    simply   the   shape's   contours'
    x-coordinates taken on the y-scanlines.


                   /---/    |---|   Note that there are usually
                  /---/     |---|   several spans per scanline.
        |        /---/      |---|
        |       /---/_______|---|   When rendering this shape to the
        V      /----------------|   current scanline y, we must
              /-----------------|   compute the x values of the
           a /----|         |---|   points a, b, c, and d.
      - - - *     * - - - - *   * - - y -   
           /     / b       c|   |d      


                   /---/    |---|   
                  /---/     |---|  And then turn on the spans a-b
                 /---/      |---|  and c-d.
                /---/_______|---|  
               /----------------|  
              /-----------------|  
           a /----|         |---| 
      - - - ####### - - - - ##### - - y -
           /     / b       c|   |d       

  b. Decomposing outlines into profiles

    For  each  scanline during  the  sweep,  we  need the  following
    information:

    o The  number of  spans on  the current  scanline, given  by the
      number of  shape points  intersecting the scanline  (these are
      the points a, b, c, and d in the above example).

    o The x coordinates of these points.

    These  are  computed  before   the  sweep,  in  a  phase  called
    `decomposition' which converts the glyph into *profiles*.

    Put it simply, a `profile'  is a contour's portion that can only
    be either ascending or descending,  i.e., it is monotonic in the
    vertical direction (we will  also say y-monotonic).  There is no
    such thing as a horizontal profile, as we shall see.

    Here are a few examples:


      this square
                                          1         2
         ---->----     is made of two
        |         |                       |         |
        |         |       profiles        |         |
        ^         v                       ^    +    v
        |         |                       |         |
        |         |                       |         |
         ----<----

                                         up        down


      this triangle

             P2                             1          2

             |\        is made of two       |         \
          ^  | \  \                         |          \
          | |   \  \      profiles         |            \      |
         |  |    \  v                  ^   |             \     |
           |      \                    |  |         +     \    v
           |       \                   |  |                \
        P1 ---___   \                     ---___            \
                 ---_\                          ---_         \
             <--__     P3                   up           down



      A more general contour can be made of more than two profiles:

              __     ^
             /  |   /  ___          /    |
            /   |     /   |        /     |       /     |
           |    |    /   /    =>  |      v      /     /
           |    |   |   |         |      |     ^     |
        ^  |    |___|   |  |      ^   +  |  +  |  +  v
        |  |           |   v      |                 |
           |           |          |           up    |
           |___________|          |    down         |

                <--               up              down


    Successive  profiles are  always joined  by  horizontal segments
    that are not part of the profiles themselves.
     
    Note that  for the  rasterizer, a profile  is simply  an *array*
    that associates one horizontal *pixel* coordinate to each bitmap
    *scanline*  crossed  by  the  contour's section  containing  the
    profile.   Note also  that profiles  are *oriented*  up  or down
    along the glyph's original flow orientation.

    In other graphics libraries, profiles are also called `edges' or
    `edgelists'.

  c. The Render Pool

    FreeType  has been designed  to be  able to  run well  on _very_
    light systems, including embedded systems with very few memory.

    A render pool  will be allocated once; the  rasterizer uses this
    pool for all  its needs by managing this  memory directly in it.
    The  algorithms that are  used for  profile computation  make it
    possible to use  the pool as a simple  growing heap.  This means
    that this  memory management is  actually easy, and  faster than
    any kind of malloc()/free() combination.
     
    Moreover,  we'll see  later that  the rasterizer  is  able, when
    dealing with profiles too large  and numerous to lie all at once
    in  the render  pool, to  immediately decompose  recursively the
    rendering process  into independent sub-tasks,  each taking less
    memory to be performed (see `sub-banding' below).

    The  render pool doesn't  need to  be large.   A 4kByte  pool is
    enough for nearly all renditions, though nearly 100% slower than
    a  more confortable  16 or  32kByte pool  (that was  tested with
    complex glyphs at sizes over 500 pixels).

  d. Computing Profiles Extents
     
    Remember that a profile is an array, associating a _scanline_ to
    the x pixel coordinate of its intersection with a contour.

    Though it's not exactly how the FreeType rasterizer works, it is
    convenient  to think  that  we need  a  profile's height  before
    allocating it in the pool and computing its coordinates.

    The profile's height  is the number of scanlines  crossed by the
    y-monotonic section of a contour.  We thus need to compute these
    sections from  the vectorial description.  In order  to do that,
    we are  obliged to compute  all (local and global)  y-extrema of
    the glyph (minima and maxima).

     
           P2             For instance, this triangle has only
                          two y-extrema, which are simply
           |\       
           | \               P2.y  as an y-maximum
          |   \              P3.y  as an y-minimum
          |    \    
         |      \            P1.y is not an y-extremum (though it is
         |       \           a x-minimum, which we don't need).
      P1 ---___   \    
               ---_\      
                     P3   

    Note  that the  extrema are  expressed  in pixel  units, not  in
    scanlines.   The triangle's  height  is certainly  (P3.y-P2.y+1)
    pixel  units,   but  its  profiles'  heights   are  computed  in
    scanlines.  The exact conversion is simply:

      - min scanline = FLOOR  ( min y )
      - max scanline = CEILING( max y )

    A problem  arises with Bezier  Arcs.  While a segment  is always
    necessarily y-monotonic (i.e.,  flat, ascending, or descending),
    which makes extrema computations easy,  the ascent of an arc can
    vary between its control points.

                          P2
                         *
                                       # on curve
                                       * off curve
                   __-x--_
                _--       -_
          P1  _-            -          A non y-monotonic Bezier arc.
             #               \ 
                              -        The arc goes from P1 to P3.
                               \
                                \  P3
                                 #

    We first  need to be  able to easily detect  non-monotonic arcs,
    according to  their control points.  I will  state here, without
    proof, that the monotony condition can be expressed as:

      P1.y <= P2.y <= P3.y   for an ever-ascending arc

      P1.y >= P2.y >= P3.y   for an ever-descending arc

    with the special case of

      P1.y = P2.y = P3.y     where the arc is said to be `flat'.

    As  you can  see, these  conditions can  be very  easily tested.
    They are, however, extremely important, as any arc that does not
    satisfy them necessarily contains an extremum.

    Note  also that  a monotonic  arc can  contain an  extremum too,
    which is then one of its `on' points:

        P1           P2
          #---__   *         P1P2P3 is ever-descending, but P1
                -_           is an y-extremum.
                  -
           ---_    \
               ->   \
                     \  P3
                      #

    Let's go back to our previous example:

                          P2
                         *
                                       # on curve
                                       * off curve
                   __-x--_
                _--       -_
          P1  _-            -          A non-y-monotonic Bezier arc.
             #               \ 
                              -        Here we have
                               \              P2.y >= P1.y &&
                                \  P3         P2.y >= P3.y      (!)
                                 #

    We  need to  compute the  y-maximum of  this arc  to be  able to
    compute a  profile's height (the  point marked by an  `x').  The
    arc's equation indicates that  a direct computation is possible,
    but we'll rely  on a different technique, which  use will become
    apparent a bit later.

    Bezier  arcs have  the  special property  of  being very  easily
    decomposed into two other sub-arcs, which are themselves Beziers
    arcs.  Moreover, it  is easy to prove that there  is at most one
    y-extremum on each Bezier arc (for second degree ones).

    For instance,  the following arc  P1P2P3 can be  decomposed into
    two sub-arcs Q1Q2Q3 and R1R2R3 that look like:

                    P2
                   *
                                    # on  curve
                                    * off curve


                                    Original Bezier Arc P1P2P3.
                __---__
             _--       --_
           _-             -_
          -                 -
         /                   \
        /                     \
       #                       #
     P1                         P3




                    P2
                   * 



                   Q3                 Decomposed into two subarcs
          Q2                R2        Q1Q2Q3 and R1R2R3
            *   __-#-__   *
             _--       --_
           _-       R1    -_          Q1 = P1         R3 = P3
          -                 -         Q2 = (P1+P2)/2  R2 = (P2+P3)/2
         /                   \                 
        /                     \            Q3 = R1 = (Q2+R2)/2
       #                       #
     Q1                         R3    Note that Q2, R2, and Q3=R1
                                      are on a single line which is
                                      tangent to the curve.

    We  have  then  decomposed  a non-y-monotonic  bezier  into  two
    smaller sub-arcs.  Note that in the above drawing, both sub-arcs
    are monotonic, and that the extremum is then Q3=R1.  However, in
    a  more general  case,  only  one sub-arc  is  guaranteed to  be
    monotonic.  Getting back to our former example:

                    Q2    
                   *                   
                                          
                   __-x--_ R1
                _--       #_
          Q1  _-        Q3  -   R2  
             #               \ *
                              -     
                               \    
                                \  R3
                                 #

    Here, we see that,  though Q1Q2Q3 is still non-monotonic, R1R2R3
    is ever  descending: we  thus know that  it doesn't  contain the
    extremum.  We can then re-subdivide Q1Q2Q3 into two sub-arcs and
    go  on recursively,  stopping  when we  encounter two  monotonic
    subarcs, or when the subarcs become simply too small.

    We will  finally find the  y-extremum.  Note that  the iterative
    process of finding an extremum is called `flattening'.
    
  e. Computing Profiles coordinates

    Once we have the height of each profile, we are able to allocate
    it in  the render pool.  We  now have to  compute its coordinate
    for each scanline.

    In the case of segments, the computation is straightforward, and
    uses good  old Euclide (also  known as Bresenham  ;-).  However,
    for Bezier arcs, things get a little more complicated.

    We assume  that all Beziers that  are part of a  profile are the
    result of `flattening' the curve,  which means that they are all
    y-monotonic (ascending  or descending, and never  flat).  We now
    have  to  compute the  arcs'  intersections  with the  profile's
    scanlines.  One way is to  use a similar scheme to `flattening',
    called `stepping'.

                                 Consider this arc, going from P1 to
      ---------------------      P3.  Suppose that we need to
                                 compute its intersections with the
                                 drawn scanlines.  Again, this is
      ---------------------      feasible directly, if we dare
                                 to compute one square root per
          * P2         _---# P3  scanline (how great!). 
      ------------- _--  --
                  _-
                _/               Rather, it is still possible to use
      ---------/-----------      the decomposition property in the
              /                  same recursive way, i.e. subdivide
             |                   the arc into subarcs until these
      ------|--------------      get too small to cross more than 
            |                    one scanline!
           |
      -----|---------------      This is very easily done using a
          |                      rasterizer-managed stack of
          |                      subarcs.
          # P1

  f. Sweeping and Sorting the spans

    Once all our profiles have  been computed, we begin the sweep to
    build (and fill) the spans.

    As  the TrueType specification  uses the  winding fill  rule, we
    place  on each  scanline the  profiles present  in  two separate
    lists.

    One  list,  called  the  `left'  one,  only  contains  ascending
    profiles, while  the other `right' list  contains the descending
    profiles.

    As  each glyph  is made  of  closed curves,  a simple  geometric
    property  is that  the two  lists necessarily  contain  the same
    number of elements.

    Creating spans is there straightforward:
    
    1. We sort each list in increasing x order.

    2. We pair each  value of the left list,  with its corresponding
       value in the right one.
    

                   /     /  |   |          For example, we have here
                  /     /   |   |          four profiles.  Two of
                >/     /    |   |  |       them are ascending (1 &
              1//     /   ^ |   |  | 2     3), while the two others
              //     //  3| |   |  v       are descending (2 & 4).
              /     //4   | |   |          On the given scanline,
           a /     /<       |   |          the left list is (1,3),
      - - - *-----* - - - - *---* - - y -  and the right one is
           /     / b       c|   |d         (4,2) (sorted).

                                   There are then two spans, joining
                                   1 to 4 (i.e. a-b) and 3 to 2 
                                   (i.e. c-d)!

    Sorting doesn't necessarily  take much time, as in  99 cases out
    of 100, the lists' order is  kept from one scanline to the next.
    We can  thus implement it  with two simple  singly-linked lists,
    sorted by a classic bubble-sort, which takes a minimum amount of
    time when the lists are already sorted.

    A  previous  version  of  the  rasterizer  used  more  elaborate
    structures, like arrays to  perform `faster' sorting.  It turned
    out that  this old scheme is  not faster than  the one described
    above.

    Once the spans  have been `created', we can  simply draw them in
    the target bitmap.

  g. Drop-out control

    To be continued.


--- end of raster.txt ---
