[Freetype] Errors (and problems) in the documentation

[Peter Montgomery]

Hi,

    I am just starting to use FreeType 2.0.4 (yes, I know 2.0.5 is out,
but I already had 2.0.4 working on my system.  I used the tutorial part
one and got working text rendering working.  However, part 2 of the
tutorial is another matter.  I encountered a number of errors in the
sample code in the tutorial.  Here's a list:


 In the section on rendering using kerning and centering, the 3rd
parameter is wrong.  It's shown as a pointer to a vector component, but
it should be a pointer to a vector.

  error = FT_Glyph_To_Bitmap( &image,
                ft_render_mode_normal,
                &pen.x, // This should be "&pen", not "&pen.x"
                0 );


A little later, the mythical "my_draw_bitmap()" is called.  I'm not sure
what all is going on here.  First, there is an FT_BitmapGlyph  created
called "bit" which is never used.   Second, there is no such thing (that
I can find) called an FT_BitmapGlyph .  There is an FT_BitmapGlyphRec.
Is that what this is supposed to be?

FT_BitmapGlyph  bit = (FT_BitmapGlyph)image;

          my_draw_bitmap( bitmap->bitmap,
                          bitmap->left,
                          my_target_height - bitmap->top );

          FT_Done_Glyph( image );


In the section on filling the glyph array, there is this line which has
no terminating semi-colon:

  // record current glyph index
  previous = glyph_index

In the section on computing the Box, this line is missing the second
parameter.  Since the parameter is quite critical, this is a very tricky
omission.  I am assuming it should be "ft_glyph_bbox_subpixels" but that
is just a guess.

FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox );

Later in the same routine is this line.  Notice that instead of a
comparison, there is some strange characters.  It should say ">", not
"&gy;".  Well, I think it should be ">", but then I'm just guessing
based on the surrounding code:

  if (glyph_bbox.yMax &gy; bbox.yMax)
   bbox.yMax = glyph_bbox.yMax;

So, this is all making it extremely hard to use the docs to actually
create code that centers and kerns text.  As I mentioned before, I was
able to use the sample code in tutorial 1 without any problems.  The 2nd
tutorial is much harder due to the problems.  In fact, I still don't
have it working.  I am quite confused by this section of the code that
renders the text:

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

1 - I find no mention anywhere of what data type "string_width" is, nor
"start_x".
2 -  I just want to use the code to create the smallest bitmap with my
text on it.  I intend to then BLT that onto a larger bitmap to create
multiple sentences, etc.  How do I compute "start_x" and "start_y" then?
3 - What do I use for "my_target_width" and "my_target_height".  The
values of "string_width" and "string_width"?

I know there are sample projects.  However, they tend to be a lot more
complicated and the way to use FreeType is lost in all the noise.
Since the ability to kern and center text into the smallest bitmap
possible are probably at the heart of all uses of FreeType, it seems
that it's pretty important that these tutorials be accurate.  Can you
shed some light here?

    Thanks,
    PeterM